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ABOUT THIS CHAPTER 


Warning: This chapter has not been updated to reflect changes and improvements 
that are available on systems using 32-Bit QuickDraw. For further 
information on 32-Bit QuickDraw, please refer to the 32-Bit QuickDraw 
documentation (available on "Phil & Dave's Excellent CD: The Release 
Version). 


A new version of QuickDraw has been created to take advantage of the 
capabilities of the Macintosh II. Color QuickDraw is able to use a very large 
number of colors and can take advantage of systems that have one or more screens 
of any size. This chapter describes the use of color with one screen. The 
following chapter, "Graphics Devices", explains what your program should do to 
Support more than one screen. 


The features of Color QuickDraw implemented for the Macintosh Plus, the 
Macintosh SE, and the Macintosh II are 


¢ Text drawing modes are enhanced, and now include a text mask mode, 
drawing with multibit fonts, and fractional character positioning. 

e The QuickDraw picture format (PICT) has been enhanced, and includes 
a number of new opcodes. 


Some of the features of Color QuickDraw for the Macintosh II are 


e All drawing operations supported by old QuickDraw can now be 
performed in color. 

¢ Color QuickDraw supports the use of as many as 2%48 colors; however, 
current hardware can only support 2%24 colors, and this assumes the 
presence of 32-Bit QuickDraw. In addition, Color QuickDraw's color 
model is hardware-independent, allowing programs to operate 
independently of the display device. 

¢ Color QuickDraw includes several new data types: color tables, 
color icons, color patterns, and color cursors. These types can 
be stored as resources that are easily used by your program. 

e A new set of transfer modes has been added. These modes allow colors 
to be blended with or added to the colors that are already on the screen. 

« Most Toolbox Managers have been enhanced to use color. Thus you can 
now add color to windows, menus, controls, dialog boxes, and TextEdit 
text. Refer to the appropriate chapters for more information. 

e The QuickDraw picture format (PICT) has been extended so that Color 
QuickDraw images can be recorded in pictures. 


This chapter introduces the basic concepts, terminology, and data structures 
underlying the Macintosh II approach to graphics. The material presented here 
assumes familiarity with the QuickDraw concepts described in the QuickDraw 
chapter, such as bit maps, graphics ports, patterns, cursors, and transfer 
modes. You should also be familiar with the use of resources, as presented in 
the Resource Manager chapter. 
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COLOR REPRESENTATION 


The following sections introduce the basic concepts and terminology used in 
Color QuickDraw. It's important to keep in mind that Color QuickDraw is designed 
to be device-independent. The range of colors available is the result of the 
system configuration: the screen resolution, the graphics hardware used to 
produce color, and the software used to select and store color values. Color 
QuickDraw provides a consistent way of dealing with color, regardless of the 
characteristics of the video card or display device. 


The original QuickDraw represents each dot on the screen (known as a pixel) as a 
single bit in memory. Each bit can have two values, zero or one. This allows two 
colors, usually black and white, to be displayed. 


To produce color graphics, more than one bit of memory per pixel displayed is 
needed. If two bits per pixel are available, four colors can be displayed. Four 
bits per pixel provides a display of 16 colors, and eight bits per pixel 
provides a display of 256 colors. The bits in a pixel, taken together, form a 
number known as the pixel value. 


The number of possible colors is related to the amount of memory used to store 
each pixel. Since displayed pixels are stored in RAM on the video card, rather 
than in the RAM in the Macintosh, the quality of the graphics depends on 
capabilities of the video card used. 


RGB Space 


Color QuickDraw represents colors in RGB space. Each color has a red, a green, 
and a blue component, hence the name RGB. These components may be visualized as 
being mapped into a color cube, as shown in Figures 1 and 2. (Figure 1 is a 
color representation of Figure 2.) 
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0.0.65535 = blue 


0.0.0 = black 


0.65535.0 = sreen 


69955.0.0 = red 


B5535.60000.09935 = White Figure 1-RGB Color Cube (Color Yersion) 
Figure 1—-RGB Color Cube (Color Version) 
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69550.05590 65555 = white 


0.0.65535 = blue 


0.0.0 = black 


0.65536.0 = green 


65535.0.0 = red 


Figure 2-RGB Color Cube (BIW Yersion) 
Figure 2—RGB Color Cube (B/W Version) 


The data structures used within Color Quickdraw express each RGB component as an 
unsigned integer value. Each R, G, and B can have a value from $0000 to $FFFF 
(or @ to 65,535). RGB color is additive; that is, as the value of a component is 
increased, the amount of that component in the total color increases. An RGB 
color is black if all three components are set to 0, or white if each component 
is set to 65,535. Pixel values between these two extremes can be combined to 
represent all the possible colors. For instance, pixel values that lie along the 
diagonal between black and white, and for which R = G = B, are all perceived as 
shades of gray. 


Other Color Spaces 


In addition to RGB, several other color models are commonly used to represent 
colors. These other models include HSV (hue, saturation, value), HLS (hue, 
lightness, saturation), and CMY (cyan, magenta, yellow). If you wish to work in 
a different color space in your program, you can use the conversion routines 
provided in the Color Picker Package to convert colors to their RGB equivalents 
before passing them to Color QuickDraw. Please refer to the Color Picker Package 
chapter for more details. 
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USING COLOR ON THE MACINTOSH II 


Before you read about the details of how to use Color QuickDraw, it's useful to 
understand the various components of the color system and how they interact with 
each other. This section, through a series of rules and examples, attempts to 
illustrate these interactions. 


Rule 1: The user selects the depth of the screen using the Control Panel. 


This rule is mentioned first to convey the fundamental need for device 
independence. Your application shouldn't change the depth of the screen, because 
it must avoid conflicts with desk accessories or other applications that are 
using the screen at the same time. Let the user decide how many colors should be 
displayed. 


Rule 2: Work with colors in RGB space, not with the colors on the screen. 


Whenever possible, your application should assume that it's drawing to a screen 
that has 2°48 colors. Let Color QuickDraw determine what colors to actually 
display on the screen. This lets your program work better when drawing to 
devices that support more colors. 


The easiest way to follow this rule is for a program to call the Color Picker 
Package to select colors. The Color Picker returns an RGB value, which can then 
be used as the current color. When Color QuickDraw draws using that color, it 
selects the color that best matches the specified RGB. 


Rule 3: To ensure good color matching, and to avoid conflict with other 
applications and desk accessories, use the Palette Manager. 


If your program requires a very specific set of colors not found in the default 
selection of colors, for instance 128 levels of gray, then you should use the 
Palette Manager. The Palette Manager lets you specify the set of colors that is 
to be used by a particular window. When that window is brought to the front, its 
set of colors is switched in (with a minimal amount of impact on the rest of the 
screen). 


You should also use the Palette Manager if your application needs to animate 
colors (that is, to change the colors of pixels that are already displayed). 


The Palette Manager is a powerful tool because it makes sure that your 
application gets the best selection of colors across multiple screen devices and 
multiple screen depths. You don't have to worry about interactions with desk 
accessories or other applications. Please refer to the chapter on the Palette 
Manager for more information on using the Palette Manager routines. 


Rule 4: Be aware that systems may have multiple video devices. 


Since the Macintosh II is able to support multiple screen devices, make sure 
your application takes into account the variable-sized desktop. For instance, a 
document may have been dragged to an alternate screen on one system, and then 
copied and used on another system. You should leave the document positioned 
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where it is if it lies within the desktop, but move it to the main screen if it 
doesn't. Please refer to the Graphics Devices chapter for more details. 


Figure 3 helps to illustrate the relationships between the various parts of the 
color system. 


Color QudeckDraw 


Figure 3-The Macintosh II Color System 
Figure 3—The Macintosh II Color System 


From Color to Pixel 


To help illustrate the interconnections of the color system, let's examine the 
steps from the specification of a color to the display of that color on the 
screen. This is an oversimplified explanation that you should use for conceptual 
understanding only. 


First, you specify the color that you want to display. Color QuickDraw stores 
the RGB components so that it knows the exact color that you specified. Let's 
assume that the screen is set to eight bits per pixel. This means that each 
pixel is able to have 2%8, or 256, different values. Associated with the screen 
is a structure called a color table, which is a list of all the colors that the 
screen is currently able to display. So in this case the color table has 256 RGB 
values in it, one for each possible pixel value. The first entry in the color 
table specifies the color of all pixels that have value 0, the second entry 
specifies the color of pixels that have value 1, and so on. Thus the color's 
position in the table determines the pixel value that produces that color. 


When you use Color QuickDraw to draw something, it retrieves the stored RGB, and 
asks the Color Manager to return the pixel value that best represents that 
color. The Color Manager effectively searches through the color table for the 
RGB that most closely matches your color. The position in the table of the best 
match determines the pixel value to be placed on the screen. Color QuickDraw 
then places that pixel value on the screen. 
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But how does this pixel cause the assigned color to be displayed? Color 
QuickDraw has placed this pixel into the RAM on the video card. While your 
Macintosh II is turned on, the video card is continuously redisplaying every 
pixel that is stored in its RAM (very, very quickly). Internal to the video card 
is another color table, the Color Look-Up Table (CLUT). It is organized exactly 
like the first one, but is used the other way around. The video card takes the 
pixel value and uses it to determine what RGB value that pixel represents. It 
then uses that RGB to send off three signals (red, green, and blue) to the video 
monitor, indicating exactly what color the current pixel should be. 


Some video cards allow you to change the set of colors displayed at a given 
time. Although this is normally done transparently through the Palette Manager, 
it actually happens when both the screen's color table and the one that is 
internal to the video card are changed to reflect the new set of colors. 


A very slight variation of this is used to support the monochrome mode that you 
can set from the control panel. When you set monochrome mode, the screen's color 
table doesn't change: from the application's point of view, the same set of 
colors is still available. Instead, when the video card is told to use 
monochrome mode, it replaces each entry in the video card's internal color table 
with a level of gray (R=G=B) that matches the luminance of the color it is 
replacing. Because of this, the switch between color and monochrome modes has no 
effect on a running program. 
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ABOUT COLOR QUICKDRAW 


The most fundamental difference between the original QuickDraw and Color 
QuickDraw is the environment in which drawing takes place. In the original 
QuickDraw, all drawing is performed in a grafPort, the structure that defines 
the coordinate system, drawing pattern, background pattern, pen size and 
location, character font and style, and bit map in which drawing takes place. In 
Color QuickDraw, drawing takes place in a color grafPort (cGrafPort) instead. As 
described in later sections, most of the fields in a cGrafPort are the same as 
fields in a grafPort; however, a few fields have been changed to hold color 
information. 


When you're using a grafPort in your application, you can specify up to eight 
colors. When drawing to a color screen or printing, these colors will actually 
be displayed. When drawing to an offscreen bitmap, the colors will be lost 
(since an offscreen bitmap only has one bit for each pixel). 


When you're using a cGrafPort, however, you can specify up to 2%48 colors. The 
number of colors that are displayed depends on the setting of the screen, the 
capability of the printer, or the depth of the offscreen pixmap. There is more 
information about offscreen pixmaps in the "Drawing to Offscreen Devices" 
section of the next chapter. 


Color grafPorts are used by the system in the same way as grafPorts. They are 
the same size as grafPorts, and they are the structures upon which a program 
builds color windows. As with a grafPort, you set thePort to be a cGrafPort 
using the SetPort command. 


You can use all old drawing commands when drawing into a cGrafPort, and you can 
use all new drawing commands when drawing into a grafPort. However, since new 
drawing commands that are used in a grafPort don't take advantage of any of the 
features of Color QuickDraw, it's not recommended. 


Drawing Color in a GrafPort 


Although the QuickDraw graphics routines were designed mainly for monochrome 
drawing, they also included some rudimentary color capabilities. A pair of 
fields in the grafPort record, fgColor and bkColor, allow a foreground and 
background color to be specified. The color values used in these fields are 
based on a planar model: each bit position corresponds to a different color 
plane, and the value of each bit indicates whether a particular color plane 
should be activated. (The term color plane refers to a logical plane, rather 
than a physical plane.) The individual color planes combine to produce the 
full-color image. 


The standard QuickDraw color values consist of one bit for normal monochrome 
drawing (black on white), one bit for inverted monochrome (white on black), 
three bits for the additive primary colors (red, green, blue) used in video 
display, and four bits for the subtractive primary colors (cyan, magenta, 
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yellow, black) used in hardcopy printing. The original QuickDraw interface 
includes a set of predefined constants for the standard colors: 


CONST 
blackColor = 33; 
whiteColor = 30; 
redColor = 209; 
greenColor = 329; 
blueColor = 389; 
cyanColor = 269; 
magentaColor = 149; 
yellowColor = 89; 


These are the only colors available in the original QuickDraw. All programs that 
draw into grafPorts are limited to these eight colors. When these colors are 
drawn to the screen on the Macintosh II, Color QuickDraw automatically draws 
them in color, if the screen is set to a color mode. 


Drawing Color in a CGrafPort 


Color QuickDraw represents color using the RGBColor record type, which specifies 
the red, blue, and green components of the color. Three 16-bit unsigned integers 
give the intensity values for the three additive primary colors: 


TYPE 
RGBColor = RECORD 
red: INTEGER; {red component} 
green: INTEGER; {green component} 
blue: INTEGER {blue component} 
END; 


A color of this form is referred to as an RGB value and is the form in which an 

application specifies the colors it needs. The translation from the RGB value to 
the pixel value is performed at the time the color is drawn. At times the pixel 
value is stored in the fgColor or bkColor fields. Refer to the Graphics Devices 

chapter for more details. 


When drawing is actually performed, QuickDraw calls the Color Manager to supply 
the color that most closely matches the requested color for the current device. 
As described in the Color Manager chapter, you can replace the method used for 
color matching if necessary. Normally pixel values are handled entirely by Color 
QuickDraw and the Color Manager; applications only refer to colors as RGB 
values. 


A set of colors is grouped into a structure called a color table: 


TYPE 

CTabHandle = “CTabPtr; 

CTabPtr = “ColorTable; 

ColorTable = RECORD 
ctSeed: LONGINT; {unique identifier from table} 
ctFlags: INTEGER; {contains flags describing the } 

{ specArray; clear for a pixMap} 

ctSize: INTEGER; {number of entries -1 } 
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{ in ctTable} 
ctTable: cSpecArray 
END; 


The fields of a color table are fully described in the Color Manager chapter. 
The ctFlags field contains flags that differentiate between a device color table 
and an image color table. The ctTable field is composed of a cSpecArray, which 
contains an array of ColorSpec entries. Notice that each entry in the color 
table is a ColorSpec, not simply an RGBColor. The type ColorSpec is composed of 
a value field and an RGB value, as shown below. 


TYPE 
cSpecArray : ARRAY [0..0] of ColorSpec; 
ColorSpec = RECORD 


value: INTEGER; {pixel value} 
rgb: RGBColor {RGB value} 
END; 


Color tables are used to represent the set of colors that a device is capable of 
displaying, and they are used to describe the desired colors in an image. If the 
color table describes an image's colors, then a ColorSpec determines the desired 
RGB for the pixel value stored in the value field. This is the most common 
usage, and most of the routines described in this chapter work with a ColorSpec 
in this manner. 


If the color table describes a device's colors, then the value field ina 
ColorSpec is reserved for use by the Color Manager. In most cases your 
application won't change the device color table. If you want to know more about 
the device color table, refer to the Color Manager chapter for more details. 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 « Apple Computer 
COLOR QUICKDRAW e 12 of 78 


THE COLOR GRAPHICS PORT 


As described above, programs designed to take advantage of the more powerful new 
color facilities available on the Macintosh II must use a new form of graphics 


port, the color graphics port (type cGrafPort). 


Color grafPorts will generally 


be created indirectly, as a result of opening a color window with the new 
routines NewCWindow, GetNewCWindow, and NewCDialog. 


In addition, the old routines GetNewWindow, GetNewDialog, Alert, StopAlert, 
NoteAlert, and CautionAlert will open a color grafPort if certain resources 
(types 'wctb', ‘dctb', or 'actb') are present. Refer to the chapters on the 
Window and Dialog Managers for more details. 


The new cGrafPort structure is the same size as the old-style grafPort and most 
of its fields are unchanged. The old portBits field, which formerly held a 
complete 14-byte BitMap record embedded within the grafPort, has been replaced 
by a 4-byte PixMapHandle (portPixMap), freeing 10 bytes for other uses. (In 
particular, the new portVersion field, in the position previously occupied by 
the bit map's rowBytes field, always has its two high 


bits set; these bits are used to distinguish cGrafPorts from grafPorts, in which 
the two high bits of rowBytes are always clear. See Figure 4.) Similarly, the 
old bkPat, pnPat, and fillPat fields, which previously held 8-byte patterns, 
have been replaced by three 4-byte handles. The resulting 12 bytes of additional 
Space are taken up by two 6-byte RGBColor records. 


The structure of the color graphics port is as follows: 


CGrafPtr 
CGrafPort 


“CGrafPort; 
RECORD 
device: 


portPixMap: 
portVersion: 


grafVars: 
chExtra: 
pnLocHFrac: 
portRect: 
visRgn: 
clipRgn: 
bkPixPat: 
rgbFgColor: 


rgbBkColor: 


pnLoc: 
pnSize: 
pnMode: 
pnPixPat: 
fillPixPat: 
pnVis: 


INTEGER; 


PixMapHandle; 
INTEGER; 


Handle; 
INTEGER; 
INTEGER; 
Rect; 
RgnHandle; 
RgnHandle; 
PixPatHandle; 
RGBColor; 


RGBColor; 


Point; 

Point; 
INTEGER; 
PixPatHandle; 
PixPatHandle; 
INTEGER; 


{device ID for font } 

{ selection} 

{port's pixel map} 
{highest 2 bits always } 
{ set} 

{handle to more fields} 
{extra characters} 

{pen fraction} 

{port rectangle} 
{visible region} 
{clipping region} 
{background pattern} 
{requested foreground } 
{ color} 

{requested background } 
{ color} 

{pen location} 

{pen size} 

{pen transfer mode} 
{pen pattern} 

{fill pattern} 

{pen visibility} 
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txFont: INTEGER; {font number for text} 


txFace: Style; {text's character style} 
txMode: INTEGER; {text's transfer mode} 
txSize: INTEGER; {font size for text} 
spExtra: Fixed; {extra space} 

fgColor: LONGINT; factual foreground color} 
bkColor: LONGINT; factual background color} 
colrBit: INTEGER; {plane being drawn} 
patStretch: INTEGER; {used internally} 
picSave: Handle; {picture being saved} 
rgnSave: Handle; {region being saved} 
polySave: Handle; {polygon being saved} 
grafProcs: CQDProcsPtr {low-level drawing } 


{ routines} 
END; 


Field descriptions 


portPixMap The portPixMap field contains a handle to the port's pixel 
map. This is the structure that describes the cGrafPort's pixels. 


portVersion The two high bits of the portVersion field are always set. 
This allows Color QuickDraw to tell the difference between a 
grafPort and a cGrafPort. The remainder of the field gives 
the version number of Color QuickDraw that created this port. 
(Initial release is version 0.) 


grafVars The grafVars field contains a handle to additional fields. 


chExtra The chExtra field is used in proportional spacing. It specifies 
a fixed point number by which to widen every character, 
excluding the space character, in a line of text. (The number 
is in 4.12 fractional notation: four bits of signed integer 
followed by 12 bits of fraction. This number is multiplied by 
txSize before it is used.) Default chExtra is 0. 


pnLocHFrac The pnLocHFrac field contains the fractional horizontal pen 
position used when drawing text. The initial pen fraction is 1/2. 

bkPixPat The bkPixPat field contains a handle to the background pixel 
pattern. 

rgbFgColor The rgbFgColor field contains the requested foreground color. 

rgbBkColor The rgbBkColor field contains the requested background color. 

pnPixPat The pnPixPat field contains a handle to the pixel pattern for 


pen drawing. 


FillPixPat The fillPixPat field contains a handle to the pixel pattern for 
area fill; for internal use only. Notice that this is not in 
the same location as old fillPat. 


fgColor The fgColor field contains the pixel value of the foreground 
color supplied by the Color Manager. This is the best available 
approximation to rgbFgColor. 
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bkColor The bkColor field contains the pixel value of the background 
color supplied by the Color Manager. This is the best available 
approximation to rgbBkColor. 

colrBit The colrBit field is reserved: not for use by applications. 


grafProc The grafProc field used with a cGrafPort contains a CQDProcsPtr, 
instead of the QDProcsPtr used with a grafPort. 


All remaining fields have the same meanings as in the old-style grafPort. 


bts D1 is iim ge Fasc d sai 0 grafPort portBits rowBytes 
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Figure 4-—Color QuicEDraw Fields 


Figure 4—Color QuickDraw Fields 


Pixel Images 


The representation of a color image in memory is a pixel image, analogous to the 
bit image used by the original QuickDraw. The number of bits per pixel is called 
the depth of the image; a pixel image one bit deep is equivalent to a bit image. 
On the Macintosh II, the pixel image that appears on a video screen is normally 
stored on a graphics card rather than in main memory. To increase speed, your 
program can build additional images in RAM for rapid transfer to the display 
device. This technique, called drawing to an offscreen bitmap, is described in 
the Graphics Devices chapter. 


There are several possible arrangements of a pixel image in memory. The size and 
structure of a pixel image is described by the pixel map data structure; this 
structure and its various forms are discussed below. See Figure 5 for a 
representation of a pixel image on a system with screen depth set to eight. 


Pixel Maps 


Just as the original QuickDraw does all of its drawing in a bit map, Color 
QuickDraw uses an extended data structure called a pixel map (pixMap). In 
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addition to the dimensions and contents of a pixel image, the pixel map also 
includes information on the image's storage format, depth, resolution, and color 


usage: 


TYPE 


PixMapHandle 


PixMapPtr 
PixMap 


= “PixMapPtr; 
= “PixMap; 
= RECORD 
baseAddr: Ptr; {pointer to pixMap data} 
rowBytes: INTEGER; {offset to next row} 
bounds: Rect; {boundary rectangle} 
pmVersion: INTEGER; {color QuickDraw version } 
{ number} 
packType: INTEGER; {packing format} 
packSize: LONGINT; {size of data in packed } 
{ state} 
hRes: Fixed; {horizontal resolution} 
vRes: Fixed; {vertical resolution} 
pixelType: INTEGER; {format of pixel image} 
pixelSize: INTEGER; {physical bits per pixel} 
cmpCount: INTEGER; {logical components per } 
{ pixel} 
cmpSize: INTEGER; {logical bits per component} 
planeBytes: LONGINT; {offset to next plane} 
pmTable: CTabHandle; {absolute colors for this } 
{ image} 
pmReserved: LONGINT {reserved for future } 
{ expansion} 
END; 


Field descriptions 


baseAddr 


rowBytes 


bounds 


pmVersion 


packType 


The baseAddr field contains a pointer to first byte of the 
pixel image, the same as in a bitMap. For optimal performance 
this should be a multiple of four. 


The rowBytes field contains the offset in bytes from one row of 
the image to the next, the same as in a bitMap. As before, 
rowBytes must be even. The high three bits of rowBytes are used 
as flags. If bit 15 = 1, the data structure is a pixMap; 
otherwise it is a bitMap. Bits 14 and 13 are not used and must 
be 0. 


The bounds field is the boundary rectangle, which defines the 

coordinate system and extent of the pixel map; it's similar to 
a bitMap. This rectangle is in pixels, so depth has no effect 

on its values. 


The pmVersion is the version number of Color QuickDraw that 
created this pixel map, which is provided for future 
compatibility. (Initial release is version 0.) 


The packType field identifies the packing algorithm used to 
compress image data. Color QuickDraw currently supports only 
packType = 0, which means no packing. 
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packSize The packSize field contains the size of the packed image in 
bytes. When packType = 0, this field should be set to 0. 


hRes The hRes is the horizontal resolution of pixMap data in pixels 
per inch. 
vRes The vRes is the vertical resolution of pixMap data in pixels 


per inch. By default, hRes = vRes = 72 pixels per inch. 


pixelType The pixelType field specifies the storage format for a pixel 
image. 0 = chunky, 1 = chunky/planar, 2 = planar. Only chunky 
is used in the Macintosh II. 


pixelSize The pixelSize is the physical bits per pixel; it's always a 
power of 2. 
cmpCount The cmpCount is the number of color components per pixel. For 


chunky pixel images, this is always 1. 


cmpSize The cmpSize field contains the logical bits per RGBColor 
component. Note that (cmpCount*cmpSize) doesn't necessarily 
equal pixelSize. For chunky pixel images, cmpSize = pixelSize. 


planeBytes The planeBytes field is the offset in bytes from one plane to 
the next. If only one plane is used, as is the case with chunky 
pixel images, this field is set to 0. 


pmTable The pmTable field is a handle to table of colors used in the 
pixMap. This may be a device color table or an image color table. 


pmReserved The pmReserved field is reserved for future expansion; it must 
be set to 0 for future compatibility. 


The data in a pixel image can be organized several ways, depending on the 
characteristics of the device or image. The pixMap data structure supports three 
pixel image formats: chunky, planar, and chunky/planar. 


In a chunky pixel image, all of a pixel's bits are stored consecutively in 
memory, all of a row's pixels are stored consecutively, and rowBytes indicates 
the offset in memory from one row to the next. This is the only one of the three 
formats that's supported by this implementation of Color QuickDraw. The pixel 
depths that are currently supported are 1, 2, 4, and 8 bits per pixel. Ina 
chunky pixMap cmpCount = 1 and cmpSize = pixelSize. Figure 5 shows a chunky 
pixel image for a system with screen depth set to eight. 


A planar pixel image is a pixel image separated into distinct bit images in 
memory, one for each color plane. Within the bit image, rowBytes indicates the 
offset in memory from one row to the next. PlaneBytes indicates the offset in 
memory from one plane to the next. The planar format isn't supported by this 
implementation of Color QuickDraw. 


A chunky/planar pixel image is separated into distinct pixel images in memory, 
typically one for each color component. Within the pixel image, rowBytes 
indicates the offset in memory from one row to the next. PlaneBytes indicates 
the offset in memory from one plane to the next. The chunky/planar format isn't 
Supported by this implementation of Color QuickDraw. 
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Figure 5-A Pixel Image 


Pixel Patterns 


With Color QuickDraw, monochrome patterns are replaced by a new form of pattern 
structure, the pixel pattern, which offers greater flexibility in the use of 


color. 


The three pattern fields in a grafPort—pnPat, bkPat, and fillPat—have 


been replaced by the pnPixPat, bkPixPat, and fillPixPat fields in a cGrafPort. 


The format for a 


TYPE 
PixPatHandle 
PixPatPtr 
PixPat 


pixel pattern is shown below: 


“PixPatPtr; 

“PixPat; 

RECORD 
patType: INTEGER; 
patMap: PixMapHandle; 
patData: Handle; 
patXData: Handle; 
patXValid: INTEGER; 
patXMap: Handle; 
patlData: Pattern; 

END; 


{pattern type} 

{pattern characteristics} 
{pixel image defining } 
{ pattern} 

{expanded pixel image} 
{flags for expanded } 

{ pattern data} 

{handle to expanded } 

{ pattern data} 
{old-style pattern/RGB } 
{ color} 
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Field descriptions 


patType The patType field specifies the pattern's type. The possible 
values include: 0 = old-style pattern, 1 = full-color pixel 
pattern, 2 = RGB pattern. 


patMap The patMap field is a handle to the pixel map describing the 
pattern's pixel image. 

patData The patData field is a handle to the pattern's pixel image. 

patXData The patXData field is a handle to an expanded pixel image used 
internally by Color QuickDraw. 

patXValid When the pattern's data or color table change, you can 
invalidate the expanded data by setting the patXValid field to -1. 

patXMap The patXMap field is a handle that is reserved for use by Color 
QuickDraw. 


patlData The patlData field contains an old-style 8-by-8 pattern to be 
used when this pattern is drawn into old grafPort. NewPixPat 
sets this field to 50% gray. 


Old-style patterns are still supported. When used in a cGrafPort, the QuickDraw 
routines PenPat and BackPat store the pattern within pnPixPat and bkPixPat, 
respectively, and set the patType to 0 to indicate that the structure contains 
old pattern data. Such patterns are limited to the original 8-by-8 dimensions 
and are always drawn using the values in the cGrafPort's rgbFgColor and 
rgbBkColor fields. Similarly, filled drawing operations, such as FillRect, are 
also supported. 


In a pixel pattern (patType = 1), the pattern's dimensions, depth, resolution 
(only 72 pixels per inch is supported), set of colors, and other characteristics 
are defined by a pixel map, referenced by the patMap handle. Since the pixel map 
has its own color table, pixel patterns can consist of any number of colors, and 
don't usually use the foreground and background colors. The section on relative 
patterns, below, describes an exception to this rule. 


Furthermore, patType = 1 patterns are not limited to a fixed size: their height 
and width can be any power of 2, as specified by the height and width of 
patMap**. bounds. (Notice that a pattern eight bits wide—the original QuickDraw 
Size—has a row width of just one byte, contrary to the usual rule that the 
rowBytes field must be even.) This pattern type is generally read into memory 
using the GetPixPat routine, or set using the PenPixPat or BackPixPat routines. 


Although the patMap defines the pattern's characteristics, its baseAddr field is 
ignored; for a typel pattern, the actual pixel image defining the pattern is 
stored in the handle in the pattern's patData field. The pattern's depth need 
not match that of the pixel map it's painted into; the depth will be adjusted 
automatically when the pattern is drawn. Color QuickDraw maintains a private 
copy of the pattern's pixel image, expanded to the current screen depth, and 
aligned to the current grafPort or cGrafPort, in the patXData field. 
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The third pattern type is RGBPat (patType = 2). Using the MakeRGBPat routine, 
the application can specify the exact color it wants to use. QuickDraw selects a 
pattern to approximate that color. In this way, an application can effectively 
increase the color resolution of the screen. Pixel patterns are particularly 
useful for dithering: mixing existing colors together to create the illusion of 
a third color that's unavailable on a particular device. The MakeRGBPat routine 
aids in this process by constructing a dithered pattern to approximate a given 
absolute color. (See the description of MakeRGBPat in the 

"Color QuickDraw Routines" section for more details.) In the current 
implementation of Color QuickDraw, an RGBPat can display 125 different patterns 
on a 4-bit-deep screen, or 2197 different patterns on an 8-bit-deep screen. 


For an RGBPat, the RGB defines the image; there is no image data. An RGBPat has 
an 8-by-8, 2-bit-deep pattern. 


A program that creates a pixMap must initialize the pixMap's color table to 
describe the pixels. GetCTable could be used to read such a table from a 
resource file; you could then dispose of the pixMap's color table and replace it 
with the one returned by GetCTable. 


Relative Patterns 


Typel pixel patterns contain color tables that describe the colors they use. 
Generally such a color table contains one entry for each color used in the 
pattern. For instance, if your pattern has five colors in it, you would probably 
create a four-bit-per-pixel pattern that uses pixel values 0-4, and a color 
table with five entries, numbered 0-4, that contain the RGB specifications for 
those pixel values. 


When the pattern is drawn, each possible pixel value that isn't specified in the 
color table is assigned a color. The largest unassigned pixel value becomes the 
foreground color; the smallest unassigned pixel value is assigned the background 
color. Remaining unassigned pixel values are given colors that are evenly 
distributed between the foreground and background. 


For instance, in the color table mentioned above, pixel values 5-15 are unused. 
Assume that the foreground color is black and the background color is white. 
Pixel value 15 is assigned the foreground color, black; pixel value 5 is 
assigned the background color, white; the nine pixel values between them are 
assigned evenly distributed shades of gray. If the pixMap's color table is set 
to NIL, all pixel values are determined by blending the foreground and 
background colors. 


Transfer Modes 


A transfer mode is a method of placing information on the display devices. It 
involves an interaction between what your application is drawing (the source) 
and what's already there (the destination). The original QuickDraw offered eight 
basic transfer modes: 


* completely replacing the destination with the source (Copy), and its 
inverse (NotCopy) 

* combining the destination with the source (Or), and its inverse (NotOr) 

« selectively clearing the destination with the source (Bic, for "bit 
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clear"), and its inverse (NotBic) 
« selectively inverting the destination with the source (Xor), and its 
inverse (NotXor) 


This is how color affects these eight transfer modes when the source pixels are 
either black (all 1's) or white (all 0's): 


Copy The Copy mode applies the foreground color to the black part of 
the source (the part containing 1's) and the background color to 
the white part of the source (the part containing 0's), and 
replaces the destination with the colored source. 


NotCopy The NotCopy mode applies the foreground color to the white part 
of the source and the background color to the black part of the 
source, and replaces the destination with the colored source. It 
thus has the effect of reversing the foreground and background 
colors. 


Or The Or mode applies the foreground color to the black part of the 
source and replaces the destination with the colored source. The 
white part of the source isn't transferred to the destination. If 
the foreground is black, the drawing will be faster. 


NotOr The NotOr mode applies the foreground color to the white part of 
the source and replaces the destination with the colored source. 
The black part of the source isn't transferred to the destination. 
If the foreground is black, the drawing will be faster. 


Bic The Bic mode applies the background color to the black part of 
the source and replaces the destination with the colored source. 
The white part of the source isn't transferred to the destination. 


NotBic The NotBic mode applies the background color to the white part 
of the source and replaces the destination with the colored source. 
The black part of the source isn't transferred to the destination. 


Xor The Xor mode complements the bits in the destination corresponding 
to the bits equal to 1 in the source. When used on a colored 
destination, the color of the inverted destination isn't defined. 


NotXor The NotXor mode inverts the bits that are 0 in the source. When 
used on a colored destination, the color of the inverted 
destination isn't defined. 


Pixels of colors other than black and white aren't all 1's or all 0's, so the 
application of a foreground color or a background color to the pixel produces an 
undefined result. For this reason, and because a pixPat already contains color, 
the foreground and background colors are ignored when your application is 
drawing with a pixPat. When your program draws a pixMap the foreground and 
background colors are not ignored. Make sure that the foreground is black and 
the background is white before you call CopyBits or the result will be 
undefined. 


If you intend to draw with pixMaps or pixPats, you will probably want to use the 
Copy mode or one of the arithmetic modes described in the following section. 
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To help make color work well on different screen depths, Color QuickDraw does 
some validity checking of the foreground and background colors. If your 
application is drawing to a cGrafPort with a depth equal to 1 or 2, and if the 
RGB values of the foreground and background colors aren't the same, but both of 
them map to the same pixel value, then the foreground color is inverted. This 
ensures that, for instance, red text drawn on a green background doesn't map to 
black on black. 


Arithmetic Drawing Modes 


Color QuickDraw uses a set of arithmetic drawing modes designed specifically for 
use with color. These modes change the destination pixels by performing 
arithmetic operations on the source and destination pixels. These drawing modes 
are most useful in 8-bit color, but work on 4-bit and 2-bit color as well. If 
the destination bitmap is one bit deep, the mode reverts to one of the old 
transfer modes that approximates the arithmetic mode requested. 


Each drawing routine converts the source and destination pixels to their RGB 
components, performs an operation on each pair of components to provide a new 
RGB value for the destination, and then assigns the destination a pixel value 
close to the calculated RGB value. The arithmetic modes listed below can be used 
for all drawing operations; your application can pass them as a parameter to 
TextMode, PenMode, or CopyBits. 


addOver This mode assigns to the destination pixel the color closest to 
the sum of the source and destination RGB values. If the sum of 
any of the RGB components exceeds the maximum allowable value, 
65,535, the RGB value wraps around to the value less 65,536. 
AddOver is slightly faster than addPin. If the destination bitmap 
is one bit deep, addOver reverts to Xor. 


addPin This mode assigns to the destination pixel the color closest to 
the sum of the destination RGB values, pinned to a maximum allowable 
RGB value. For grafPorts, the pin value is always white. For 
cGrafPorts, the pin value is assigned using OpColor. If the 
destination bitmap is one bit deep, addPin reverts to Bic. 


subOver This mode assigns to the destination pixel the color closest to 
the difference of the source and destination RGB values. If the 
result is less than 0, the RGB value wraps around to 65,536 less 
the result. SubOver is slightly faster than subPin. If the 
destination bitmap is one bit deep, subOver reverts to Xor. 


subPin This mode assigns to the destination pixel the color closest to 
the difference of the sum and the destination RGB values, pinned 
to a minimum allowable RGB value. For grafPorts, the pin value is 
always black. In a cGrafPort, the pin value is assigned by using 
OpColor. If the destination bitmap is one bit deep, subPin reverts 
to Or. 


adMax (Arithmetic Drawing Max) This mode compares the source and 
destination pixels, and replaces the destination pixel with the 
color containing the greater saturation of each of the RGB 
components. Each RGB component comparison is done independently, 
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so the resulting color isn't necessarily either the source or the 
destination color. If the destination bitmap is one bit deep, 
adMax reverts to Bic. 


adMin (Arithmetic Drawing Min) This mode compares the source and 
destination pixels, and replaces the destination pixel with 
the color containing the lesser saturation of each of the RGB 
components. Each RGB component is compared independently, so 
the resulting color isn't necessarily the source or the 
destination color. If the destination bitmap is one bit deep, 
adMin reverts to Or. 


blend This mode replaces the destination pixel with a weighted average 
of the colors of the source and destination pixels. The formula 
used to calculate the destination is: 


dest = source*weight/65,536 + destination*(1-weight/65,536) 


where weight is an unsigned value between 1 and 65,535. In a 
grafPort, the weight is set to 50% gray, so that equal weights 
of the source and destination RGB components are combined to 
produce the destination color. In a cGrafPort, the weight is an 
RGBColor that individually specifies the weights of the red, 
green, and blue components. The weight is assigned using OpColor. 
If the destination bitmap is one bit deep, blend reverts to Copy. 


Because drawing with the arithmetic modes uses the closest matching pixel 
values, and not necessarily exact matches, these modes might not produce the 
results you expect. For instance, suppose srcCopy mode is used to paint a green 
pixel on the screen in 4-bit mode. Of the 16 colors available, the closest green 
may contain a small amount of red, as in RGB components of 300 red, 65,535 
green, and 0 blue. AddOver is then used to paint a red pixel on top of the green 
pixel, ideally resulting in a yellow pixel. The red pixel's RGB components are 
65,535 red, 0 green, and 0 blue. Adding the red components together wraps to 
300, since the largest representable value is 65,535. In this case, AddOver 
would cause no visible change at all. Using AddPin with an opColor of white 
would produce the desired results. 


On the Macintosh II the rules for setting the pen mode and the text mode have 
been relaxed slightly. It's no longer necessary to specify a pattern mode or a 
source mode (patCopy as opposed to srcCopy) to perform a particular operation. 
QuickDraw will choose the correct drawing mode automatically. However, to be 
compatible with earlier versions of QuickDraw, you application must specify the 
correct drawing mode. Text and bitmaps should always use a source mode; 
rectangles, regions, polygons, arcs, ovals, round rectangles, and lines should 
always use a pattern mode. 


The constants used for the arithmetic transfer modes are as follows: 


CONST 
blend = 32; 
addPin = 33; 
addOver = 34; 
subPin = 35; 
adMax = 37; 
subOver = 38; 
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adMin = 39; 


Warning: Unlike the rest of QuickDraw, the arithmetic modes don't call the 
Color Manager when mapping a requested RGB value to a pixel value. 
If your application replaces the color matching routines, you must 
either not use these modes, or you must maintain the inverse table 
using the Color Manager routines. 


Replace with Transparency 


The transparent mode replaces the destination pixel with the source pixel if the 
source pixel isn't equal to the background color. This mode is most useful in 8- 
bit, 4-bit, or 2-bit color modes. To specify a transparent pattern, use the 
drawing mode transparent+patCopy. If the destination pixMap is one bit deep, the 
mode is translated to Or. Transparency can be specified as a parameter to 
TextMode, PenMode, or CopyBits. 


Transparent mode is optimized to handle source bitmaps with large transparent 
holes, as an alternative to specifying an unusual clipping region or mask 
parameter to CopyMask. Patterns aren't optimized, and may not draw as quickly. 
The constant used for transparent mode is 


CONST 
transparent = 36; 


The Hilite Mode 


This new method of highlighting exchanges the background color and the highlight 
color in the destination. This has the visual effect of using a highlighting pen 
to select the object. For instance, TextEdit uses the hilite mode to select 
text: if the highlight color is yellow, selected text appears on a yellow 
background. In general, highlighting should be used in place of inversion when 
selecting and deselecting objects such as text or graphics. 


There are two ways to use hilite mode. The easiest is to call 
BitClr (Ptr(HiliteMode, pHiliteBit) ); 


just before calling InvertRect, InvertRgn, InvertArc, InvertRoundRct, or 
InvertPoly or any drawing using srcXor mode. On a one-bit-deep destination, this 
will work exactly like inversion, and is compatible with all versions of 
QuickDraw. Color QuickDraw resets the hilite bit after performing each drawing 
operation, so the hilite bit should be cleared immediately before calling a 
routine that is to do highlighting. Routines that formerly used Xor inversion, 
such as the Invert routines, Paint, Frame, LineTo, text drawing, and CopyBits, 
will now use hilite mode if the hilite bit is clear. 


Assembly language note: You can use 


BCLR #hiliteBit, hiliteMode 
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Do not alter the other bits in HiliteMode. 


The second way to use hilite mode is to pass it directly to TextMode, PenMode, 
or CopyBits as a parameter. 


Hilite mode uses the source or pattern to decide which bits to exchange; only 
bits that are on in the source or pattern can be highlighted in the destination. 


A very small inversion should probably not use hilite mode, because a small 
selection in the hilite color might be too hard to see. TextEdit, for instance, 
uses hilite mode to select and deselect text, but not to blink the insertion 
point. 


Hilite mode is optimized to look for consecutive pixels in either the hilite or 
background colors. For example, if the source is an all black pattern, the 
highlighting will be especially fast, operating internally on a long word at a 
time instead of a pixel at a time. Highlighting a large area without such 
consecutive pixels (a gray pattern, for instance) can be slow. 


The global variable HiliteRGB is read from parameter RAM when the machine 
starts. Old grafPorts use the RGB values in the global HiliteRGB as the 
highlight color. Color grafPorts default to the global HiliteRGB, but can be 
overridden by the HiliteColor procedure. 


The constants used with hilite mode are listed below: 


CONST 
hilite = 50; 
pHiliteBit = 0; {this is the correct value for use when calling } 


{ the BitClear trap. BClr must use the assembly } 
{ language equate hiliteBit} 
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THE COLOR CURSOR 


Color QuickDraw supports the use of color cursors. The size of a cursor is still 
16-by-16 pixels. The new CCrsr data structure is substantially different from 
the Cursor data structure used with the original QuickDraw: the CCrsr fields 
crsriData, crsrMask, and crsrHotSpot are the only fields that have counterparts 
in the Cursor record. 


The structure of the color cursor is as follows: 


TYPE 
CCrsrHandle = *CCrsrPtr; 
CCrsrPtr = “CCrsr; 
CCrsr = RECORD 
crsr Type: INTEGER; {type of cursor} 
crsrMap: PixMapHandle; {the cursor's pixmap} 
crsrData: Handle; {cursor's data} 
crsrxXData: Handle; {expanded cursor data} 
crsrxXValid: INTEGER; {depth of expanded data} 
crsrxXHandle: Handle; {Reserved for future } 
{ use} 
crsrilData: Bits16; {one-bit cursor} 
crsrMask: Bits16; {cursor's mask} 
crsrHotSpot: Point; {cursor's hotspot} 
crsrXTable: LONGINT; {private} 
crsrID: LONGINT; {ctSeed for expanded } 
{ cursor} 
END; 


You will not normally need to manipulate the fields of a color cursor. Your 
application can load in a color cursor using the GetCCursor routine, and display 
it using the SetCCursor routine. When the application is finished using a color 
cursor, it should dispose of it using the DisposCCursor routine. These routines 
are discussed below in the section "Color QuickDraw Routines". 


Color cursors are stored in resources of type 'crsr'. The format of the ‘'crsr' 
resource is given in the section "Color QuickDraw Resource Formats". 


Field descriptions 


crsrlype The crsrType field specifies the type of cursor. Possible 
values are: $8000 = old cursor, $8001 = new cursor. 

crsrMap The crsrMap field is a handle to the pixel map defining the 
cursor's characteristics. 

crsrData The crsrData field is a handle to the cursor's pixel data. 

crsrxData The crsrXData field is a handle to the expanded pixel image 
used internally by Color QuickDraw (private). 

crsrxValid The crsrXValid field contains the depth of the expanded cursor 
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image. If you change the cursor's data or color table, you 
should set this field to 0 to cause the cursor to be reexpanded. 
You should never set it to any other values. 


crsrxXHandle The crsrXHandle field is reserved for future use. 


crsri1Data The crsriData field contains a 16-by-16 one-bit image to be 
displayed when the cursor is on 1-bit or 2-bit per pixel screens. 


crsrMask The crsrMask field contains the cursor's mask data. The same 
1-bit-deep mask is used with crsrData and crsrlData. 


crsrHotSpot The crsrHotSpot field contains the cursor's hot spot. 
crsrXTable The crsrXTable field is reserved for future use. 
crsrID The crsriID field contains the ctSeed for the cursor. 


The first four fields of the CCrsr record are similar to the first four fields 
of the PixPat record, and are used in the same manner by Color QuickDraw. See 
the discussion of the patMap field under the section titled "Pixel Patterns" for 
more information on how the crsrMap is used. 


The display of a cursor involves a relationship between a mask, stored in the 
crsrMask field with the same format used for old cursor masks, and an image. 
There are two possible sources for a color cursor's image. When the cursor is on 
a screen whose depth is one or two bits per pixel, the image for the cursor is 
taken from CrsriData, which contains old-style cursor data. In this case, the 
relationship between data and mask is exactly as before. When the screen depth 
is greater than two bits per pixel, the image for the cursor is taken from 
crsrMap and crsrData; the relationship between mask and data is described in the 
following paragraph. 


The data pixels within the mask replace the destination pixels. The data pixels 
outside the mask are displayed using an XOR with the destination pixels. If data 
pixels outside the mask are 0 (white), the destination pixels aren't changed. If 
data pixels outside the mask are all 1's (black), the destination pixels are 
complemented. ALl other values outside of the mask cause unpredictable results. 


To work properly, a color cursor's image should contain white pixels 

(R = G = B = $FFFF) for the transparent part of the image, and black pixels 

(R = G = B = $0000) for the inverting part of the image, in addition to the 
other colors in the cursor's image. Thus, to define a cursor that contains two 
colors, it's necessary to use a 2-bit-per-pixel cursor image (that is, a four- 
color image). 


If your application changes the value of your cursor data or its color table, it 
should set the crsrXValid field to 0 to indicate that the cursor's data needs to 
be reexpanded, and assign a new unique value to crsrID (unique values can be 
obtained using the GetCTSeed routine); then it should call SetCCursor to display 
the changed cursor. 
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COLOR ICONS 


A new data structure, known as CIcon, supports the use of color icons. The 
structure of the color icon is as follows: 


TYPE 
CIconHandle = “*CIconPtr; 
CIconPtr = “CIcon; 
CIcon = RECORD 
iconPMap: PixMap; {the icon's pixMap} 
iconMask: BitMap; {the icon's mask bitmap} 
iconBMap: BitMap; {the icon's bitMap} 
iconData: Handle; {the icon's data} 
iconMaskData: ARRAY[0..0] OF INTEGER; 
{icon's mask and bitmap } 
{ data} 
END; 


You won't normally need to manipulate the fields of color icons. Your 
application can load a color icon into memory using the routine GetCIcon. To 
draw a color icon that's already in memory, use PlotCIcon. When your application 
is through with a color icon, it can dispose of it using the DisposCIcon 
routine. These routines are discussed below in the section "Color QuickDraw 
Routines". 


Color icons are stored in a resource file as resource type 'cicn'. The format of 
the 'cicn' resource is given in the section "Using Color QuickDraw 
Resources". 


Field descriptions 


iconPMap The iconPMap field contains the pixel map describing the 

icon. Note that pixMap is inline, not a handle. 
iconMask The iconMask field contains a bit map for the icon's mask. 
iconBMap The iconBMap field contains a bit map for the icon. 
iconData The iconData field contains a handle to the icon's pixel image. 
iconMaskData The iconMaskData field is an array containing the icon's mask 


data followed by the icon's bitmap data. This is only used 
when the icon is stored as a resource. 


You can use color icons in menus in the same way that you could use old icons in 
menus. The menu definition procedure first tries to load in a 'cicn' with the 
specified resource ID. If it doesn't find one, then it tries to load in an 
'ICON' with that ID. The Dialog Manager will also use a 'cicn' in place of an 
'ICON' if there is one with the ID specified in the item list. For more 
information, see the Menu Manager and Dialog Manager chapters. 
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USING COLOR QUICKDRAW 


This section gives an overview of routines that you will typically call while 
using Color QuickDraw. All routines are discussed below in the section "Color 
QuickDraw Routines". 


Using a color graphics port is much like using an old-style grafPort. The old 
routines SetPort and GetPort operate on grafPorts or cGrafPorts, and the global 
variable ThePort points to either to a grafPort or a cGrafPort. Color QuickDraw 
examines the two high bits of the portBits.rowBytes field (the portVersion field 
in a cGrafPort). If these bits equal 0, then it is a grafPort; if they are both 
1, then it is a cGrafPort. In Pascal, use type coercion to convert between 
GrafPtr and cGrafPtr. For example: 


VAR myPort: CGrafPtr; 
SetPort (GrafPtr(myPort) ); 


There's still a graphics pen for line drawing, with a current size, location, 
pattern, and transfer mode; all of the old line- and shape-drawing operations, 
such as Move, LineTo, FrameRect, and PaintPoly, still work just as before. 
However, colors should be set with the new routines RGBForeColor and 
RGBBackColor (described below) instead of the old ForeColor and BackColor 
routines. If your application is using the Palette Manager, use the routines 
PMForeColor and PMBackColor instead. 


PenPat and BackPat are still supported, and will construct a pixel pattern 
equivalent to the specified bit pattern. The patType field of this pattern is 
set to 0; thus it will always use the port's current foreground and background 
colors at the time of drawing. 


To read a multicolored pattern from a resource file, use the GetPixPat routine. 
Set these patterns using PenPixPat and BackPixPat, or pass them as parameters to 
Color QuickDraw's color fill routines (such as FillCRect). These patterns have 
their own color tables and are generally not affected by the port's foreground 
and background colors (refer to the earlier discussion of relative patterns). 


Most routines that accept bitMaps as parameters also accept pixMaps (not 
PixMapHandles). Likewise, any new routine that has a pixMap as a parameter will 
also accept a bitMap. This allows one set of routines to work for all operations 
on images; the high bit of the rowBytes field distinguishes whether the 
parameter is a bitMap or a pixMap. 


It's worth noting here that resources are used slightly differently by Color 
QuickDraw than they were used by QuickDraw. For instance, with old QuickDraw, 
your application could call GetCursor before each SetCursor; the same handle 
would be passed back to the application each time. With Color QuickDraw, the 
color cursor is a compound structure, more complex than a simple resource 
handle. Color QuickDraw reads the requested resource, copies it, and then alters 
the copy before passing it to the application. Each time your application calls 
GetCCursor, it gets a new copy of the cursor. This means that your program 
should only call GetCCursor once, even if it does multiple SetCCursor calls. The 
new resource types should be marked as purgeable if you are concerned about 
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memory space. This discussion holds true for color cursor, color pattern, color 
icon, and color table resources. 
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COLOR QUICKDRAW ROUTINES 


Color QuickDraw continues to support all the original QuickDraw calls described 
in the QuickDraw chapter. The following sections describe in detail the new 
Color QuickDraw routines, as well as changes to existing routines. 


Operations on CGrafPorts 
PROCEDURE OpenCPort (port: CGrafPtr); 


The OpenCPort procedure is analogous to OpenPort, except it opens a cGrafPort 
instead of a grafPort. You will rarely need to use this call, since OpenCPort is 
called by NewCWindow and GetNewCWindow, as well as by the Dialog Manager when 
the appropriate color resources are present. OpenCPort allocates storage for 
all the structures in the cGrafPort, and then calls InitCPort to initialize 
them. The new structures allocated are the portPixMap, the pnPixPat, the 
fillPixPat, the bkPixPat, and the grafVars handle. The GrafVars record 
structure is shown below: 


TYPE 
GrafVars = RECORD 
rgbOpColor: RGBColor; {color for addPin, subPin, and } 
{ blend} 
rgbHiliteColor: RGBColor; {color for highlighting} 
pmFgColor: Handle; {Palette handle for foreground } 
{ color} 
pmFgIndex: INTEGER; {index value for foreground} 
pmBkColor: Handle; {Palette handle for background } 
{ color} 
pmBkIndex: INTEGER; {index value for background} 
pmF lags: INTEGER; {Flags for Palette Manager} 
END; 


The rgbOpColor field is initialized as black, and the rgbHiliteColor field is 
initialized as the default HiliteRGB. All the rest of the GrafVars fields are 
initially zero. 


The portPixMap is not allocated a color table of its own. When InitCPort is 
called, the handle to the current device's color table is copied into the 
portPixMap. 


PROCEDURE InitCPort (port: CGrafPtr); 


The InitCPort procedure does not allocate any storage. It merely initializes all 
the fields in the cGrafPort to their default values. All old fields are 
initialized to the same values as a grafPort's fields. New fields are given the 
following values: 


portPixMap: copied from theGDevice**.GDPMap 
portVersion: $C000 
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grafVars: opColor initialized to black, rgbHiliteColor 
initialized as default HiliteRGB. All other 
fields are initialized as 0. 


chExtra: 0 
pnLocHFrac: 1/2 
bkPixPat: white 
rgbFgColor: black 
rgbBkColor: white 
pnPixPat: black 
fillPixPat: black 


The default portPixMap is set to be the same as the current device's pixMap. 
This allows you to create an offscreen port that is identical to the screen's 
grafPort or cGrafPort for drawing offscreen. If you want to use a different set 
of colors for offscreen drawing, you should create a new gDevice, and set it as 
the current gDevice before opening the cGrafPort. Refer to the section on 
offscreen bitMaps in the Graphics Devices chapter for more details. 


As mentioned above, InitCPort does not copy the data from the current device's 
color table to the portPixMap's color table. It simply replaces whatever is in 
the pmTable field with a copy of the handle to the current device's color table. 


If you try to initialize a grafPort using InitCPort, it will simply return 
without doing anything. 


PROCEDURE CloseCPort (port: CGrafPtr) ; 


CloseCPort releases the memory allocated to the cGrafPort. It disposes of the 
visRgn, the clipRgn, the bkPixPat, the pnPixPat, the fillPixPat, and the 
grafVars handle. It also disposes of the portPixMap, but doesn't dispose of the 
portPixMap's color table (which is really owned by the gDevice). If you have 
placed your own color table into the portPixMap, either dispose of it before 
calling CloseCPort, or store another reference to it for other uses. 


Setting the Foreground and Background Colors 


PROCEDURE RGBForeColor (color : RGBColor); 
PROCEDURE RGBBackColor (color : RGBColor); 


These two calls set the foreground and background colors to the best available 

match for the current device. The only drawing operations that aren't affected 

by these colors are PlotCIcon, and drawing using the new color patterns. Before 
you call CopyBits with a pixMap as the source, you should set the foreground to 
black and the background to white. 


If the current port is a cGrafPort, the specified RGB is placed in the 
rgbFgColor or rgbBkColor field (and the pixel value most closely matching that 
color is placed in the fgColor or bkColor field). If the current port is a 
grafPort, fgColor or bkColor is set to the old QuickDraw color determined by 
taking the high bit of each of the R, G, and B components, and using that three- 
bit number to select one of the eight QuickDraw colors. The ordering of the 
QuickDraw colors is shown in the GetForeColor description. 


PROCEDURE GetForeColor (VAR color : RGBColor); 
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PROCEDURE GetBackColor (VAR color : RGBColor); 


These two calls return the RGB components of the foreground and background 
colors set in the current port. The calls work for both grafPorts and 
cGrafPorts. If the current port is a cGrafPort, the returned value is taken 
directly from the rgbFgColor or rgbBkColor field. If the current port is a 
grafPort, then only eight possible RGB values can be returned. These eight 
values are determined by the values in a global variable named QDColors, which 
is a pointer to a color table containing the current QuickDraw colors. 


The colors are stored in the following order: 


Value Color Red Green Blue 
0 black $0000 $0000 $0000 
1 yellow $FCOO $F37D $052F 
2 magenta $F2D7 $0856 $84EC 
3 red $DD6B $08C2 $06A2 
4 cyan $0241 $AB54 $EAFF 
5 green $0000 $8000 $11B0 
6 blue $0000 $0000 $D400 
7 white $FFFF $FFFF $FFFF 


This is the set of colors that Color QuickDraw uses to determine precisely what 
colors should be displayed by an old grafPort that is using color. The default 
set of colors has been adjusted to match the colors produced on the ImageWriter 
II printer. 


Color Drawing Operations 


PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle) ; 

PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle) ; 

PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle) ; 
PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; ppat: PixPatHandle) ; 
PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle) ; 

PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandlLe) ; 


These calls are analogous to their similarly named counterparts in QuickDraw. 
They allow a multicolored pattern to be used for filling. 


PROCEDURE GetCPixel (h,v: INTEGER; VAR cPix: RGBColor); 


The GetCPixel function returns the RGB of the pixel at the specified position in 
the current port. 


PROCEDURE SetCPixel (h,v: INTEGER; cPix: RGBColor); 


The SetCPixel function sets the pixel at the specified position to the pixel 
value that most closely matches the specified RGB. 


Creating Pixel Maps 
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FUNCTION NewPixMap : PixMapHandle; 


The NewPixMap function creates a new, initialized pixMap data structure and 
returns a handle to it. All fields of the pixMap are copied from the current 
device's pixMap except the color table. A handle to the color table is allocated 
but not initialized. 


PROCEDURE DisposPixMap (pm: PixMapHandlLe) ; 


The DisposPixMap procedure releases all storage allocated by NewPixMap. It 
disposes of the pixMap's color table, and of the pixMap itself. Be careful not 
to dispose of a pixMap whose color table is the same as the current device's 
color table. 


PROCEDURE CopyPixMap (srcPM,dstPM: PixMapHandle) ; 


The CopyPixMap routine is used for duplicating the pixMap data structure. 
CopyPixMap copies the contents of the source pixMap data structure to the 
destination pixMap data structure. The contents of the color table are copied, 
so the destination pixMap has its own copy of the color table. Since the 
baseAddr field of the pixMap is a pointer, the pointer, but not the image 
itself, is copied. 


Operations on Pixel Maps 


PROCEDURE CopyBits (srcBits,dstBits: BitMap; srcRect, dstRect: Rect; 
mode: INTEGER; maskRgn: RgnHandle) ; 


CopyBits now accepts either bitMaps or pixMaps as parameters. For convenience, 
just as you could pass the current port*.portBits as a parameter to CopyBits, 
you can now pass GrafPtr(cPort)*.portBits. (Recall that in a cGrafPort the high 
two bits of the portVersion field are set. This field, in the same position in 
the port as portBits.rowBytes, indicates to QuickDraw that it has been passed a 
portPixMap handle. ) 


This call transfers an image from one bitMap or pixMap to another bitMap or 
pixMap. The source and destination may be of different depths, of different 
Sizes, and they may have different color tables. Note, however, that the 
destination pixMap is assumed to use the same color table as the gDevice. 
(This is because an inverse table is required for translation to the 
destination's color table.) 


During a CopyBits call, the foreground and background colors are applied to the 
image. To avoid unwanted coloring of the image, set the foreground to black and 
the background to white before calling this routine. 


PROCEDURE CopyMask (srcBits,maskBits,dstBits: BitMap; 
srcRect,maskRect,dstRect: Rect); 


CopyMask is a new version of the CopyBits procedure, introduced in the Macintosh 
Plus. It transfers an image from the source to the destination only where the 
corresponding bit of the mask equals 1. The Macintosh II version will accept 
either a bitMap or pixMap as the srcBits or dstBits parameters. The maskBits 
parameter must be a bitMap. 
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Like the Macintosh Plus version, CopyMask doesn't send any of its drawing 
commands through grafProc routines; thus CopyMask calls are not recorded in 
pictures. Unlike the Macintosh Plus version, the Macintosh II version of 
CopyMask is able to stretch the source and mask to fit the dstRect. The srcRect 
and maskRect should be the same size. CopyMask uses the same low-level code as 
CopyBits, so all the same rules regarding depth translation and color table 
translation apply. 


During a CopyMask call, the foreground and background colors are applied to the 
image. To avoid unwanted coloring, set the foreground to black and the 
background to white before calling this routine. 


PROCEDURE SeedCFill (srcBits, dstBits: BitMap; srcRect, dstRect: Rect; 
seedH, seedV: INTEGER; matchProc: ProcPtr; 
matchData: LONGINT) ; 


The SeedCFill procedure generates a mask for use with CopyMask or CopyBits, with 
bits equal to 1 only in those positions where paint can leak from the starting 
seed point, like the MacPaint® bucket tool. 


Given a rectangle within a source bitMap or pixMap (srcBits), SeedCFill returns 
a mask (dstBits) that contains 1's in place of all pixels to which paint can 
leak from the specified seed position (seedH, seedV), expressed in the local 
coordinate system of the source pixMap. By default, paint can leak to all 
adjacent pixels whose RGB value exactly match that of the seed. To use this 
default, set matchProc and matchData to zero. 


In generating the mask, SeedCFill performs CopyBits to convert srcBits to a 
one-bit mask. It installs a default searchProc into the gDevice that returns 0 
if the RGB value matches that of the seed; all other RGB values return 1's. 


If you want to customize SeedCFill, your application can specify a matchProc 
that is used instead of the default searchProc. It should return 0's for RGB 
values that you want to be filled, and 1's for values that shouldn't be filled. 
When the matchProc is called, the GDRefCon field of the current gDevice contains 
a pointer to a record having the following structure: 


MatchRec = RECORD 


red: INTEGER; 

green: INTEGER; 

blue: INTEGER; 

matchData: LONGINT 
END; 


In this record the red, green, and blue fields are the RGB of the pixel at the 
specified seed location. MatchData is simply whatever value you passed to 
SeedCFill as a parameter. For instance, your application could pass a handle to 
a color table whose entries should all be filled, and then, in the matchProc, 
check to see if the specified RGB matches any of the colors in the table. 


No automatic scaling is performed: the source and destination rectangles must be 
the same size. Calls to SeedCFill are not clipped to the current port and are 
not stored into QuickDraw pictures. 


PROCEDURE CalcCMask (srcBits, dstBits: BitMap; srcRect, dstRect: Rect; 
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seedRGB: RGBColor; matchProc: ProcPtr; matchData: LONGINT); 


This routine generates a mask (dstBits) corresponding to the area in a pixMap 
(srcBits) to which paint cannot leak from outside of the srcRect. The size of 
srcRect must be the same as the size of dstRect. By default, paint can leak to 
all adjacent pixels whose RGB values don't match that of the seedRGB. To use 
this default, set matchProc and matchData to 0. 


For instance, if srcBits contains a blue rectangle on a red background, and your 
application calls CalcCMask with the seedRGB equal to blue, then the returned 
mask has ones in the positions corresponding to the edges and interior of the 
rectangle, and zeros outside of the rectangle. 


If you want to customize CalcCMask, your application can specify a matchProc 
that is used instead of the default searchProc. It should return 1's for RGB 
values that define the edges of the mask, and 0's for values that don't. 


When the matchProc is called, the GDRefCon field of the gDevice contains a 
pointer to a MatchRec record (the structure shown in the SeedCFill description). 
The red, green, and blue fields are the RGB of the pixel at the specifed seed 
location. MatchData is simply whatever value your application passed to 
CalcCMask as a parameter. For instance, your program could pass a handle to a 
color table whose entries should all be within the mask, and then, in the 
matchProc, check to see if the specified RGB matches any of the colors in the 
table. 


No automatic scaling is performed: the source and destination rectangles must be 
the same size. Calls to CalcCMask are not clipped to the current port and are 
not stored into QuickDraw pictures. 


Operations on Pixel Patterns 
FUNCTION NewPixPat: PixPatHandle; 


The NewPixPat function creates a new pixPat data structure, and returns a handle 
to it. It calls NewPixMap to allocate and initialize the pattern's pixMap to the 
same settings as theGDevice**.GDPMap, and it sets the type of the pixPat to be a 
color pattern. The patiData field is initialized to a 50% gray pattern. New 
handles for data, expanded data, expanded map, and color table are allocated but 
not initialized. Including the pixPat itself, it allocates a total of six 
handles. You will generally not need to use this routine since the GetPixPat 
routine can be used to read in a pattern from a resource file. 


The sizes of the pixMap and pixPat handles are the size of their respective data 
structures (see the type declarations in the "Summary" section). The other three 
handles are initially small in size. Once the pattern is drawn, the size of the 
expanded data is proportional to the size of the pattern data, but adjusted to 
the depth of the screen. The color table size is the size of the record 
structure plus eight bytes times the number of colors in the table.Creating a 
PixPat 


To create a color pattern, use NewPixPat to allocate a new PixPatHandle. Set the 
rowBytes, bounds, and pixelSize of the pattern's pixMap to the dimensions of the 
desired pattern. The rowBytes should be equal to (width of bounds) *pixelSize/8; 
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it need not be even. The width and height of the bounds must be a power of two. 
Each scanline of the pattern must be at least one byte in length—-that is, (width 
of bounds)*pixelSize must be at least eight. Set the other fields in the 
pattern's pixMap as described in the section on the pixMap data structure. 


Your application can explicitly specify the color corresponding to each pixel 
value with the color table. The color table for the pattern must be placed in 
the pmTable in the pixPat's pixMap. Patterns may also contain colors that are 
relative to the foreground and background at the time that they are drawn. Refer 
to the section on the pixPat data structure for more information on relative 
patterns. 


PROCEDURE DisposPixPat (ppat: PixPatHandle) ; 


The DisposPixPat procedure releases all storage allocated by NewPixPat. It 
disposes of the pixPat's data handle, expanded data handle, and pixMap handle. 


PROCEDURE CopyPixPat (srcPP,dstPP: PixPatHandle) ; 


The CopyPixPat procedure copies the contents of the source pixPat to the 
destination pixPat. It entirely copies all fields in the source pixPat, 
including the contents of the data handle, expanded data handle, expanded map, 
pixMap handle, and color table. 


FUNCTION GetPixPat (patID: INTEGER): PixPatHandle; 


The GetPixPat call creates a new pixPat data structure, and then uses the 
information in the resource of type 'ppat' and the specified ID to initialize 
the pixPat. The 'ppat' resource format is described in the section "Color 
QuickDraw Resource Formats". If the resource with the specified ID is not found, 
then this routine returns a NIL handle. 


PROCEDURE MakeRGBPat (ppat: PixPatHandle; myColor: RGBColor); 


The MakeRGBPat procedure is a new call which generates a pixPat that 
approximates the specified color when drawn. For example, if your application 
is drawing to a device that has 4 bits per pixel, you will only get 16 colors if 
you simply set the foreground color and draw. If you use MakeRGBPat to select a 
pattern, and then draw using that pattern, you will effectively get 125 
different colors. More colors are theoretically possible; this implementation 
opted for a fast pattern selection rather than the best possible pattern 
selection. If the device has 8 bits per pixel, you will effectively get 2197 
colors. 


Note that these patterns aren't usually solid; they provide a wide selection of 
colors by alternating between colors with up to four colors in a pattern. For 
this reason lines that are one pixel wide may not look good using these 
patterns. For an RGB pattern, the patMap**.bounds always contains (0, 0, 8, 8), 
and the patMap**.rowbytes equals 2. Figure 6 shows how these colors are 
arranged. 


When MakeRGBPat creates a color table, it only fills in the last colorSpec 
field: the other colorSpec values are computed at the time the drawing actually 
takes place, using the current pixel depth for the system. 


Value RGB 
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Figure 6—RGB Pattern 


PROCEDURE PenPixPat (ppat: PixPatHandle) ; 
PROCEDURE BackPixPat (ppat: PixPatHandle) ; 


The PenPixPat and BackPixPat calls are analogous to PenPat and BackPat, but use 
multicolor pixel patterns instead of old-style patterns. If you try to use a 
pixel pattern in a grafPort, the data in the patiData field is placed into 
pnPat, bkPat, or fillPat. 


When your application sets a pixel pattern, the handle you provide is actually 
placed into the grafPort or cGrafPort. In this way, QuickDraw can expand the 
pattern once (saving it in the patXData field) when the pattern is first set, 
and won't have to reexpand it each time you set the pattern. 


Since your handle is actually stored in the grafPort or cGrafPort, it's 
considered bad form to dispose of a PixPatHandle that is currently set as the 
pnPixPat or bkPixPat. (Just in case you forget, QuickDraw will remove all 
references to your pattern from existing grafPorts or cGrafPorts when you 
dispose of it.) 


Using the old calls PenPat and BackPat, you can still set old-style patterns in 
a cGrafPort. If necessary, it creates a new pixPatHandle in which to store the 
pattern (because, as described above, pixPatHandles are owned by the 
application). As in old grafPorts, old-style patterns are drawn using the 
foreground and background colors at the time of drawing, not at the time the 
pattern is set. 
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Operations on Color Cursors 
FUNCTION GetCCursor (crsrID: INTEGER): CCrsrHandle; 


The GetCCursor call creates a new CCrsr data structure, then initializes it 
using the information in the resource of type ‘crsr' with the specified ID. The 
‘crsr' resource format is described in the section "Color QuickDraw Resource 
Formats". If the resource with the specified ID isn't found, then this routine 
returns a NIL handle. 


Since GetCCursor creates a new CCrsr data structure each time it is called, your 
application shouldn't call GetCCursor before each call to SetCCursor 

(unlike the way GetCursor/SetCursor were normally used). GetCCursor doesn't 
dispose or detach the resource, so resources of type ‘crsr' should typically be 
purgeable. 


PROCEDURE SetCCursor (cCrsr: CCrsrHandle) ; 

The SetCCursor procedure allows your application to set a multicolor cursor. At 
the time the cursor is set, it's expanded to the current screen depth so that it 
can be drawn rapidly. 

If your application has changed the cursor's data or its color table, it must 
also invalidate the fields crsrXValid and crsrID (described in the section on 
the Color Cursor data structure), before calling SetCCursor. 

PROCEDURE DisposCCursor(cCrsr: CCrsrHandle) ; 

The DisposCCursor procedure disposes all structures allocated by GetCCursor. 
PROCEDURE AllocCursor; 


The AllocCursor procedure reallocates cursor memory. Under normal circumstances, 
you should never need to use this call, since reallocation of cursor memory is 
only necessary after the depth of one of the screens has been changed. 


Operations on Color Icons 
FUNCTION GetCIcon(id: INTEGER): CIconHandle; 


The GetCIcon function allocates a CIcon data structure and initializes it using 
the information in the resource of type 'cicn' with the specified ID. It returns 
the handle to the icon's data structure. If the specified resource 

isn't found, a NIL handle is returned. 


The format of the 'cicn' resource is described in the section "Color QuickDraw 
Resource Formats". 


Since GetCIcon creates a new CIcon data structure each time it is called, your 
application shouldn't call GetCIcon before each call to PlotCIcon. GetCIcon 
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doesn't dispose or detach the resource, so resources of type '‘cicn' should 
typically be purgeable. 


PROCEDURE DisposCIcon(theIcon: CIconHandle) ; 
The DisposCIcon procedure disposes all structures allocated by GetCIcon. 
PROCEDURE PlotCIcon(theRect: Rect; theIcon: CIconHandle) ; 


The PlotCIcon procedure draws the specified icon in the specified rectangle. The 
iconMask field of the CIcon determines which pixels of the iconPMap are drawn 
and which are not. Only pixels with 1's in corresponding positions in the 
iconMask are drawn; all other pixels don't affect the destination. If the screen 
depth is one or two bits per pixel, the iconBMap is used as the source instead 
of the iconPMap (unless the rowBytes field of iconBMap is 0, indicating that 
there is no iconBMap. 


When the icon is drawn, the boundsRect of the iconPMap is used as the image's 
source rectangle. The icon and its mask are both stretched to the destination 
rectangle. The icon's pixels are remapped to the current depth and color table, 
if necessary. The bounds fields of the iconPMap, iconBMap, and iconMask are 
expected to be equal in size. 


PlotCIcon is simply a structured call to CopyMask. As such, it doesn't send any 
of its drawing commands through grafProc routines; thus, PlotCIcon calls are not 
recorded in pictures. 


Operations on CGrafPort Fields 
PROCEDURE SetPortPix (pm: PixMapHandle) ; 


The SetPortPix call is analogous to SetPortBits, and should be used instead of 
SetPortBits for cGrafPorts. It replaces the portPixMap field of the current 
cGrafPort with the specified handle. SetPortPix has no effect when used with an 
old grafPort. If SetPortBits is called when the current port is a cGrafPort, it 
does nothing. 


PROCEDURE OpColor (color: RGBColor); 


If the current port is a cGrafPort, the OpColor procedure sets the red, green, 
and blue values used by the AddPin, SubPin, and Blend drawing modes. This 
information is actually stored in the grafVars handle in the cGrafPort, but you 
should never need to reference it directly. If the current port is a grafPort, 
OpColor has no effect. 


PROCEDURE HiliteColor (color:RGBColor); 


The highlight color is used by all drawing operations that use the highlight 
transfer mode. When a cGrafPort is created, its highlight color is initialized 
from the global variable HiliteRGB. The HiliteColor procedure allows you to 
change the highlighting color used by the current port. This information is 
actually stored in the grafVars handle in the cGrafPort, but you should never 
need to reference it directly. If the current port is a grafPort, HiliteColor 
has no effect. 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
COLOR QUICKDRAW « 40 of 78 


PROCEDURE CharExtra (extra:Fixed) ; 


The CharExtra procedure sets the cGrafPort's charExtra field, which specifies 
the number of pixels by which to widen every character excluding the space 
character in a line of text. The charExtra field is stored in a compressed 
format based on the txSize field, so you must set txSize before calling 
CharExtra. The initial charExtra setting is 0. CharExtra will accept a negative 
number. CharExtra has no effect on grafPorts. 


PROCEDURE SetStdCProcs (VAR cProcs: CQDProcs); 


This procedure sets all the fields of the given CQDProcs record to point to the 
standard low-level routines. You can then change the ones you wish to point to 
your own routines. For example, if your procedure that processes picture 
comments is named MyComments, you will store @MyComments in the commentProc 
field of the CQD Procs record. 


When drawing in a cGrafPort, your application must always use SetStdCProcs 
instead of SetStdProcs. 


Operations on Color Tables 
FUNCTION GetCTable (ctID: INTEGER): CTabHandle; 


The GetCTable routine allocates a new color table data structure, and 
initializes it using the information in the resource of type 'clut' having the 
specified ID. If the specified resource is not found, a NIL handle is returned. 


If you place this handle into a pixMap, you should first dispose of the handle 
that was already there. 


The format of the 'clut' resource is given in the section "Color QuickDraw 
Resource Formats". Resource ID values 0..127 are reserved for system use. Any 
‘clut' resources defined by your application should have IDs in the range 
128..1023. This value must be in the ctSeed field in the resource, and will be 
placed in the ctSeed field of the color table (for color table identification). 
All other possible seed values are used to identify newly created color tables, 
and color tables that have been modified. 


If you modify a color table, you should invalidate it by changing its ctSeed 
field. You can get a new unique value for ctSeed using the routine GetCTSeed, 
described in the Color Manager chapter. 

PROCEDURE DisposCTable(cTable: CTabHandle) ; 


The DisposCTable procedure disposes the handle allocated for a color table. 
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COLOR QUICKDRAW RESOURCE FORMATS 


Several new resource types have been defined for use with Color QuickDraw. They 
are 


‘crsr' Color cursor resource type 

‘ppat' Pixel Pattern resource type 
‘cicn' Color Icon resource type 

‘elut' Color Look-Up Table resource type 


The precise formats of resources of these types are given below. 


It is important to note that resources are used somewhat differently by Color 
QuickDraw. For instance, with old QuickDraw, you could do a GetCursor for each 
SetCursor, and the same handle would be passed back to the application each 
time. With Color QuickDraw, the color cursor, icon, and pattern are compound 
structures, more complex than a simple resource handle. Color QuickDraw reads 
the requested resource, copies it, and then alters the copy before passing it to 
the application. Each time you call GetCCursor, you get a new copy of the 
cursor. This means that you should do one GetCCursor call for a cursor, even if 
you do multiple SetCCursor calls. These new resource types should be marked as 
purgeable if you are concerned about memory space. 


Here are the resource formats of the resources used by Color QuickDraw. All 
offsets are measured from the beginning of the resource's data. 


‘crsr' (Color Cursor) 

CCrsr {data structure describing cursor} 
crsrlype: [2 bytes] = $8001 
crsrMap: [4 bytes] = offset to pixMap structure 
crsrData: [4 bytes] = offset to pixel data 
crsrxXData: [4 bytes] = 0 
crsrxXValid: [2 bytes] = 0 
crsrXHandle: [4 bytes] = 0 
crsri1Data: [32 bytes] = 1 bit image for cursor 
crsrMask: [32 bytes] = cursor's mask 
crsrHotSpot: [4 bytes] = cursor's hotSpot (v,h) 
crsrXTable: [4 bytes] = 0 
crsrID: [4 bytes] = 0 

PixMap {pixMap describing cursor's pixel image} 
baseAddr: [4 bytes] = 0 
rowBytes: [2 bytes] = rowBytes of image 
bounds: [8 bytes] = boundary rectangle of image 
pmVersion: [2 bytes] = 0 
packType: [2 bytes] = 0 
packSize: [4 bytes] = 0 
hRes: [4 bytes] = $00480000 
vRes: [4 bytes] = $00480000 
pixelType: [2 bytes] = 0 = chunky 
pixelSize: [2 bytes] = bits per pixel in image 
cmpCount: [2 bytes] = 1 
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cmpSize: [2 bytes] = pixelsize 
planeBytes: [4 bytes] = 0 
pmTable: [4 bytes] = offset to color table data 
pmReserved: [4 bytes] = 0 
pixel data [see below] data for cursor 
color table data [see below] data for color table 


The crsrMap field of the CCrsr record contains an offset to the pixMap record 
from the beginning of the resource data. The crsrData field of the CCrsr record 
contains an offset to the pixel data from the beginning of the resource data. 
The pmTable field of the pixMap record contains an offset to the color table 
data from the beginning of the resource data. The size of the pixelData is 
calculated by subtracting the offset to the pixel data from the offset to the 
color table data. The color table data consists of a color table record 
(ctSeed, ctFlags, ctSize) followed by ctSize+1 color table entries. Each entry 
in the color table connects a pixel value used in the pixel data to an actual 
RGB. 


‘ppat' (Pixel Pattern) 


PixPat record {data structure describing pattern} 
patType [2 bytes] = 1 (full color pattern) 
patMap [4 bytes] = offset to pixMap record 
patData [4 bytes] = offset to pixel data 
patXData [4 bytes] = 0 
patXValid [2 bytes] = -1 
patXMap [4 bytes] = 0 
patlData [8 bytes] = 1 bit pattern data 

PixMap { pixMap describing pattern's pixel image } 
baseAddr [4 bytes] = 0 
rowBytes [2 bytes] = rowBytes of image 
bounds [8 bytes] = boundary rectangle of image 
pmVersion [2 bytes] = 0 
packType [2 bytes] = 0 
packSize [4 bytes] = 0 
hRes [4 bytes] = $00480000 
vRes [4 bytes] = $00480000 
pixelType [2 bytes] = 0 = chunky 
pixelSize [2 bytes] = bits per pixel in image 
cmpCount [2 bytes] = 1 
cmpSize [2 bytes] = pixelsize 
planeBytes [4 bytes] = 0 
pmTable [4 bytes] = offset to color table data 
pmReserved [4 bytes] = 0 

pixel data [see below] data for pattern 

color table data [see below] data for color table 


The patMap field of the pixPat record contains an offset to the pixMap record 
from the beginning of the resource data. The patData field of the pixPat record 
contains an offset to the pixel data from the beginning of the resource data. 
The pmTable field of the pixMap record contains an offset to the color table 
data from the beginning of the resource data. The size of the pixelData is 
calculated by subtracting the offset to the pixel data from the offset to the 
color table data. The color table data consists of a color table record 
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(ctSeed, ctFlags, ctSize) followed by ctSize+1 color table entries. Each entry 
in the color table connects a pixel value used in the pixel data to an actual 
RGB. 


'cicn' (Color Icon) 
IconPMap {pixMap describing icon's pixel image} 
baseAddr [4 bytes] = 0 
rowBytes [2 bytes] = rowBytes of image 
bounds [8 bytes] = boundary rectangle of image 
pmVersion [2 bytes] = 0 
packType [2 bytes] = 0 
packSize [4 bytes] = 0 
hRes [4 bytes] = $00480000 
vRes [4 bytes] = $00480000 
pixelType [2 bytes] = 0 = chunky 
pixelSize [2 bytes] = bits per pixel in image 
cmpCount [2 bytes] = 1 
cmpSize [2 bytes] = pixelsize 
planeBytes [4 bytes] = 0 
pmTable [4 bytes] = 0 
pmReserved [4 bytes] = 0 
IconMask {Mask used when drawing icon} 
baseAddr [4 bytes] = 0 
rowBytes [2 bytes] = rowBytes of image 
bounds [8 bytes] = boundary rectangle of image 
IconBMap {Image used when drawing to 1 bit screen} 
baseAddr [4 bytes] = 0 
rowBytes [2 bytes] = rowBytes of image 
bounds [8 bytes] = boundary rectangle of image 
IconData {placeholder for image's handle} 
[4 bytes] = 0 
MaskData {the icon's mask data } 
[n bytes] n = IconMask. rowBytes*height 
BMapData {the icon's bitMap data } 
[n bytes] n = IconBMap. rowBytes*height 
PMapCTab {the icon's color table } 
[n bytes] n = 8+(ColorTable.ctSize+1)*CTEntrySize 
PMapData {the icon's image data } 


[n bytes] n = 


In the calculations above: 


IconPMap. rowBytes*height 


height = IconPMap**.bounds.bottom—IconPMap**. bounds. top. 


IconPMap is the pixMap describing the data in the IconData field. IconMask is 
the mask that is to be applied to the data when it is drawn. IconBMap is a 
bitMap to be drawn when the destination is only one or two pixels deep. If the 
rowbytes field of IconBMap is 0, then no data is loaded in for the IconBMap, and 
IconPMap is always used when drawing the icon. MaskData is the mask's data. It 
is immediately followed by the bitMap's data (which may be NIL). Next is the 


color table describing the IconPMap, as shown below. The final entry in the 
resource is the pixMap's data. 


‘clut' (Color Table) 
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ctSeed [4 bytes] 0 


ctFlags [2 bytes] = $0000 if pixMap color table 
= $8000 if device color table 

ctSize [2 bytes] = #entries — 1 

table data [n bytes] n = 8*(ctSize+1) 


The ‘clut' resource format is an exact duplicate of a color table in memory. 
Each element in the table data is four integers (eight bytes): a value field 
followed by red, green, and blue values. If the color table is used to describe 
a pixMap, then ctFlags should be set to 0, and the value field of each entry 
contains the pixel value to be associated with the following RGB. If the color 
table is used to describe a device, then ctFlags should be set to $8000, and the 
value fields should be set to 0. In this case, the implicit values are based on 
each entry's position in the table. 


There are several default color tables that are in the Macintosh II ROMs. There 
is one for each of the standard pixel depths. The resource ID for each table is 
the same as the depth. For example, the default color table used when you 
switch your system to 8 bits per pixel mode is stored with resource ID = 8. 


There is one other default color table. This color table defines the eight 
QuickDraw colors, the colors displayed by programs using the old QuickDraw 
model. This color table has ID = 127. Its values are given in the section 
"Setting the Foreground and Background Colors". 


@ SpInside Macintosh ¢« Version 1.0 * November 1989 * Apple Computer 
COLOR QUICKDRAW « 45 of 78 


USING TEXT WITH QUICKDRAW 


This section explains those QuickDraw features which provide enhanced text 
handling for the Macintosh Plus, Macintosh SE, and Macintosh II. The drawing 
mode recommended for all applications is SrcOr, because it uses the least memory 
and will draw the entire character in all cases. The SrcOr mode will only affect 
other parts of existing characters if the characters overlap. In srcOr mode the 
color of the character is determined by the foreground color, although text 
drawing is fastest when the foreground color is black. 


With QuickDraw, characters can kern to the left and to the right. QuickDraw 
begins drawing a series of characters at the specified pen position plus the 
kernMax field (part of the Font record), plus any kerning below the baseline 
caused by italicizing the font. (The kernMax field denotes the kerning allowed 
by a given font; since its value is normally negative, most fonts kern to the 
left. Italicizing also normally moves the pen to the left.) QuickDraw then draws 
through the ending pen position, plus any kerning above the baseline caused by 
italicizing the font (normally to the right), plus any space required to handle 
the outlined or shadowed part of the character. 


To draw text in any mode, including the kerned part of the leading and trailing 
characters, it is best to draw the entire line of text at once. If the line must 
be drawn in pieces, it is best to end each piece with a space character, so that 
the succeeding piece can harmlessly kern left, and the last character drawn (a 
space) will not have any right kerning clipped. 


Macintosh Plus and Macintosh SE Note: The Macintosh Plus and Macintosh SE 
versions of QuickDraw clip a leading 
left-kerning character, and do not take 
italicizing into account when 
positioning the pen. Also, it adds a 
constant of 32 to the width of the 
character imaging rectangle, causing 
large italicized fonts to have the 
rightmost character clipped in drawing 
modes other than srcOr. 


The outline and shadow styles cause the outline and shadow of the character to 
be drawn in the foreground color. The inside of the character, if drawn at all, 
is drawn in the background color. The center of shadowed or outlined text is 
drawn in a grafPort in scrBic mode if the text mode is srcOr, for compatibility 
with old applications. This allows black text with a white outline on an 
arbitrary background. If the text mode is srcBic, the center of shadowed or 
outlined text is drawn in srcOr. 


The style underline draws the underline through the entire text line, from the 
pen starting position through the ending position, plus any offsets from font or 
italic kerning, as described above. If the underline is outlined or shadowed, 
the ends aren't capped, that is, consecutively drawn pieces of text should 
maintain a continuous underline. 


Macintosh Plus and Macintosh SE Note: QuickDraw clips the right edge of the 
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underline to the ending pen position, 
causing outlined or shadowed underlines 
to match imperfectly when text is drawn 
in sections. 


One of the reasons that SrcOr is recommended is that the maximum stack space 
required for a text font drawing operation can be considerable. Text drawing 
uses a minimum amount of stack if the mode is srcOr, the forecolor is black, the 
visRgn and clipRgn are rectangular (or at least the destination of the text is 
contained within a rectangular portion of the visRgn), the text is not scaled, 
and the text does not have to be italicized, boldfaced, outlined, or shadowed by 
QuickDraw. Otherwise, the amount of stack required to draw all of the text at 
once depends most on the size and width of the the text and the depth of the 
destination. 


If QuickDraw can't get enough stack space to draw an entire string at once, it 
will draw the string in pieces. This can produce disconcerting results in modes 
other than srcOr or srcBic if some of the characters overlap because of kerning 
or italicizing. If the mode is srcCopy, overlapping characters will be clipped 
by the last drawn character. If the mode is srcXor, pixels where the characters 
overlap are not drawn at all. If the mode is one of the arithmetic modes, the 
arithmetic rules are followed, ignoring that the destination may include part of 
the string being drawn. 


The stack space required for a drawing operation on the Macintosh II is roughly 
given by this calculation: 


(text width) * (text height) * (font depth) / (8 bits per byte ) + 3K 
Font depth normally equals the screen depth. If the amount of stack space 
available is small (less than 3.5K), QuickDraw instead uses a font depth of 1, 
which is slow, but uses less stack space. 


On the Macintosh Plus, the required stack space is roughly equal to 


(text width) * (text height) / (8 bits per byte ) + 2K 


Text Mask Mode 


For the Macintosh II, the maskConstant may be added to another drawing mode to 
cause just the character portion of the text to be applied in the current 
transfer mode to the destination. If the text font contains more than one color, 
or if the drawing mode is an arithmetic mode or hilite mode, the mask mode 
causes only the portion of the characters not equal to the background to be 
drawn. 


The arithmetic drawing modes and hilite mode apply the character's background to 
the destination; this can lead to undesirable results if the text is drawn in 
pieces. The leftmost part of a text piece is drawn on top of a previous text 
piece if the font kerns to the left. The maskMode supplied in addition to these 
modes causes only the foreground part of the character to be drawn. The only 
reasonable way to kern to the right in text mask mode is to use srcOr, or to add 
trailing characters. This is because the rightmost kern is clipped. 
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The constant used with maskMode is 


CONST 
mask = 64; 


Drawing with Multibit Fonts 


Multibit fonts may have a specific color. The transfer modes may not produce the 
desired results with a multibit font. The arithmetic modes, transparent mode, 
and hilite mode work equally well with single bit and multibit fonts. 


Unlike single bit fonts, multibit fonts draw quickly in srcOr only if the 
foreground is white. Single bit fonts draw quickly in srcOr only if the 
foreground is black. Grayscale fonts produce a spectrum of colors, rather than 
just the foreground and background colors. 


Fractional Character Positioning 


CGrafPorts maintain the fractional horizontal pen position, so that a series of 
text drawing calls will accumulate the fractional position. The horizontal pen 

fraction is initially set to 1/2. InitPort, Move, MoveTo, Line and LineTo reset 
the pen position to 1/2. For an old grafPort, the pen fraction is hard-coded to 
1/2. 
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COLOR PICTURE FORMAT 


With the introduction of the Macintosh II, the QuickDraw picture structure has 
been extended to include new color graphics opcodes. The new version 2 pictures 
and opcodes solve many of the major problems encountered by developers in using 
PICT files, and enable future expandibility. For example, it is now possible to 
specify the resolution of bitMap data. Color can also be specified, but only 
chunky pixels (contiguously stored pixel components) are currently recognized by 
Color QuickDraw. Your application only needs to generate or recognize the chunky 
pixel format. This format is indicated by an image or pixMap with a cmpCount = 
1. 


Most existing applications can use version 2 pictures without modification. Ona 
Macintosh II, version 2 pictures will draw in color (if drawn directly to the 
screen). Currently, they will print using the old QuickDraw colors. Eventually, 
new print drivers will be able to take advantage of the new color information. 


On a Macintosh 512K enhanced, Macintosh Plus, and Macintosh SE, a patch in the 
System file beginning with version 4.1 provides QuickDraw with the capability to 
convert and display version 2 pictures. The original Macintosh and Macintosh 512 
can't display version 2 pictures. 


Applications that generate pictures in the QuickDraw picture format are free to 
use any or all available features to support their particular needs. Some will 

use only the imaging features. You may wish to include comments in the picture 

that are pertinent to the needs of your application. In general, put a minimal 
amount of information in your PICT files and avoid redundancy. It's reasonable 

for receiving applications to ignore picture opcodes that aren't needed. 


Differences Between Version 1 and Version 2 Pictures 
The major differences between version 1 and version 2 pictures are listed below. 


e Version 1 opcodes are a single byte; version 2 opcodes are 2 bytes in 
length. This means that old opcodes in a version 2 picture take up two 
bytes, not one. 

e Version 1 data may start on byte boundaries; version 2 opcodes and data 
are always word-aligned. 

e In version 2, the high bit of the rowBytes field is used to indicate a 
pixMap instead of a bitMap; pixData then replaces bitData. 

e All unused version 2 opcodes, as well as the number of data bytes 
associated with each, have been defined. This was done so that picture 
parsing code can safely ignore unknown opcodes, enabling future use 
of these opcodes in a backward-compatible manner. 


Drawing With Version 2 Pictures in Old GrafPorts 
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Enhancements to the DrawPicture routine allow pictures created with Color 
QuickDraw to be used in either a cGrafPort or an old-style grafPort. You can 
create a picture using the new drawing commands in a cGrafPort, cut it, and then 
paste it into an application that draws into an old grafPort. The picture will 
lose some of its detail when transferred in this way, but should be sufficient 
for most purposes. The following considerations apply to the use of this 
technique: 


e The rgbFgColor and rbgBkColor fields are mapped to the old-style 
Quickdraw constant (one of eight) that most closely approximates that 
color. For a grafPort with depth greater than one, even old applications 
will be able to draw color pictures. 

e Patterns created using MakeRGBPat are drawn as old-style patterns having 
approximately the same Luminance as the original pattern. 

e Other new patterns are replaced by the old-style pattern contained 
in the patiData field of the PixPat data structure. This field is 
initialized to 50% gray by the NewPixPat routine, and is initialized 
from the resource in a GetPixPat call. 

¢ PixMaps in the picture are drawn without interpretation. The CopyBits 
call performs all necessary mapping to the destination screen. If 
the picture is drawn on a Macintosh Plus or a Macintosh SE, or if the 
BitsProc routine has been replaced by the application, the pixMap is 
converted to a bitMap before it's drawn. 

e Changes to the ChExtra and pnLocHFrac fields, and the Hilite color 
and OpColor, are ignored. 


A new standard opcodeProc, SetStdCProc, is called by QuickDraw when it is 
playing back a color picture and it sees a new opcode that it doesn't recognize. 
The default routine simply reads and ignores all undefined opcodes. 


Picture Representation 


The PICT file is a data fork file with a 512-byte header, followed by a picture 
(see Figure 7). This data fork file contains a QuickDraw (and now, Color 
QuickDraw) data structure within which a graphic application, using standard 
QuickDraw calls, places drawing opcodes to represent an object or image graphic 
data. In the QuickDraw picture format, pictures consist of opcodes followed by 
picture data. 
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PICT file 
(type=PICT) 


5i2-hyte header 
This fork is 


PICT files 
picture data 


EndorPicture 


Figure 7—PICT file format 
Figure 7—PICT file format. 


Picture Parsing 


The first 512 bytes of a PICT data file contain application-specific header 
information. Each QuickDraw (and Color QuickDraw) picture definition consists of 
a fixed-size header containing information about the size, scaling, and version 
of the picture, followed by the opcodes and picture data defining the objects 
drawn between the OpenPicture and ClosePicture calls. 


When the OpenPicture routine is called and the port is an old grafPort, a 
version 1 picture is opened. When the OpenPicture routine is called and the port 
is a cGrafPort, then a version 2 picture is opened. If any fields in the 
grafPort are different than the default entries, those fields that are different 
get recorded in the picture. 


Version 4.1 of the Macintosh System file incorporates a patch to QuickDraw that 
will enable QuickDraw (on machines with 128K or larger ROMs) to parse a version 
2 PICT file, read it completely, attempt to convert all Color QuickDraw color 
opcodes to a suitable black-and-white representation, and draw the picture in an 
old grafPort. If you are trying to display a version 2 picture on a Macintosh 
without the system patch, QuickDraw won't be able to draw the picture. 
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Picture Record Structure 


The Pascal record structure of version 1 and version 2 pictures is exactly the 
same. In both, the picture begins with a picSize, then a picFrame (rect), 
followed by the picture definition data. Since a picture may include any 
sequence of drawing commands, its data structure is a variable-length entity. It 
consists of two fixed-length fields followed by a variable-length field: 


TYPE Picture = RECORD 


picSize: INTEGER; {low order 16 bits of picture } 
{ size} 
picFrame: Rect; {picture frame, used as } 


{ reference for scaling when } 
{ the picture is drawn } 
{picture definition data} 
END; 


To maintain compatibility with the original picture format, the picSize field 
has not been changed in version 2 pictures. However, the information in this 
field is only useful if your application supports version 1 pictures not 
exceeding 32K bytes in size. Because pictures can be much larger than the 32K 
limit imposed by the 2-byte picSize field, use the GetHandleSize call to 
determine picture size if the picture is in memory or the file size returned in 
pBFGetInfo if the picture resides in a file. 


The picFrame field is the picture frame that surrounds the picture and gives a 
frame of reference for scaling when the picture is played back. The rest of the 
structure contains a compact representation of the image defined by the opcodes. 
The picture definition data consists of a sequence of the opcodes listed in 
Table 3 in the Pict Opcodes section, each followed by zero or more bytes of 
data. Every opcode has an implicit or explicit size associated with it that 
indicates the number of data bytes following that opcode, ranging from 2 to 
2°32 bytes (this maximum number of bytes applies to version 2 pictures only). 


Picture Spooling 


In the past, images rarely exceeded the 32K practical limit placed on resources. 
Today, with the advent of scanners and other image input products, images may 
easily exceed this size. This increase in image size necessitates a means for 
handling pictures that are too large to reside entirely in memory. One solution 
is to place the picture in the data fork of a PICT file, and spool it in as 
needed. To read the file, an application can simply replace the QuickDraw 
default getPicProc routine with a procedure (getPICTData) that reads the picture 
data from a disk file; the disk access would be transparent. Note that this 
technique applies equally to version 1 (byte-opcode) and version 2 

(word-opcode) pictures. 


Spooling a Picture From Disk 


In order to display pictures of arbitrary size, an application must be able to 
import a QuickDraw picture from a file of type PICT. (This is the file type 
produced by a Save As command from MacDraw® with the PICT option selected. ) 
What follows is a small program fragment that demonstrates how to spool in a 
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picture from the data fork of a PICT file. The picture can be larger than the 
historical 32K resource size limitation. 


{ The following variable and procedure must be at the } 
{ main level of the program } 
VAR 
globalRef: INTEGER; 


PROCEDURE GetPICTData(dataPtr: Ptr; byteCount: INTEGER) ; 
{replacement for getPicProc routine} 


VAR 
err : INTEGER; 
longCount: LONGINT; 


BEGIN 
LongCount := byteCount; 
{longCount is a Pascal VAR parameter and must be a LONGINT} 
err := FSRead(globalRef, LongCount,dataPtr) ; 
{ignore errors here since it is unclear how to handle them} 
END; 


PROCEDURE GetandDrawPICTFile; 
{procedure to draw in a picture from a PICT file selected by the user} 


VAR 
wher: Point; {where to display dialog} 
reply: SFReply; {reply record} 
myFileTypes: SFTypeList; {more of the Standard File goodies} 
NumFileTypes: INTEGER; 
err: OSErr; 
myProcs: QDProcs; {use CQDProcs for a CGrafPort (a color } 
{ window) } 
PICTHand: PicHandle; {we need a picture handle for DrawPicture} 
LongCount: LONGINT; 
myPB: ParamBlockRec; 


BEGIN 
wher.h := 20; 
wher.v := 20; 
NumFileTypes := 1; {Display PICT files} 
myFileTypes[0] := 'PICT'; 


SFGetFile(wher,'',NIL,NumFileTypes,myFileTypes,NIL, reply) ; 
IF reply.good THEN BEGIN 
err := FSOpen(reply. fname, reply.vrefnum,globalRef) ; 


SetStdProcs(myProcs); {use SetStdCProcs for a CGrafPort} 
myWindow*.grafProcs := @myProcs; 
myProcs.getPicProc := @GetPICTData; 


PICTHand := PicHandle(NewHandle(SizeOf (Picture) )); 
{get one the size of (size word + frame rectangle) } 


{skip (so to speak) the MacDraw header block} 
err := SetFPos(globalRef, fsFromStart,512); 
longCount := SizeOf(Picture) ; 
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{read in the (obsolete) size word and the picture frame} 
err := FSRead(globalRef, LongCount,Ptr(PICTHand’) ); 


DrawPicture(PICTHand, PICTHand**.picFrame) ; 

{inside of DrawPicture, QD makes repeated calls to } 

{ getPicProc to get actual picture opcodes and data. Since } 
{ we have intercepted GetPicProc, QD will call myProcs to } 
{ get getPicProc, instead of calling the default procedure} 


err := FSClose(globalRef) ; 


myWindow*.grafProcs := NIL; 
DisposHandle(Handle(PICTHand) ) ; 


END; {IF reply.good} 
END; 


Spooling a Picture to a File 


Spooling a picture out to a file is equally straightforward. By replacing the 
standard putPicProc with your own procedure, you can create a PICT file and 
spool the picture data out to the file. 


Here is a sample of code to use as a guide: 


{these variables and PutPICTData must be at the main program level} 
VAR PICTcount: LONGINT; {the current size of the picture} 
globalRef: INTEGER; {the file system reference number} 
newPICThand: PicHandle; 
{this is the replacement for the StdPutPic routine} 
PROCEDURE PutPICTData(dataPtr: Ptr; byteCount: INTEGER) ; 
VAR lLongCount: LONGINT; 
err: INTEGER; 
BEGIN {unfortunately, we don't know what to do with errors} 
longCount := byteCount; 
PICTCount := PICTCount + byteCount; 
err := FSWrite(globalRef, longCount, dataPtr); {ignore error..} 
IF newPICTHand <> NIL THEN newPICTHand**.picSize := PICTCount; 
{update so QD can track the size for oddness and pad out to full words} 
END; 
{Note that this assumes the picture is entirely in memory which wouldn't } 
{ always be the case. You could (in effect) be feeding the StdGetPic } 
{ procedure at the same time, or simply spooling while drawing. } 
PROCEDURE SpoolOutPICTFile(PICTHand: PicHandle {the picture to spool}); 
VAR err: OSErr; 
i: INTEGER; 
wher: Point; { where to display dialog } 
longCount, Zero: LONGINT; 
pframe: Rect; 
reply: SFReply; { reply record } 
myProcs: QDProcs; {use CQDProcs for a CGrafPort (a color window) } 
BEGIN 


wher.h := 20; 

wher.v := 20; 

{get a file to output to} 

SFPutFile(wher, 'Save the PICT as:', ‘untitled', NIL, reply); 
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IF reply.good THEN 


BEGIN 
err := Create(reply.fname, reply.vrefnum, '????', 'PICT'); 
IF (err = noerr) | (err = dupfnerr) THEN 
BEGIN 


{now open the target file and prepare to spool to it} 
signal(FSOpen(reply.fname, reply.vrefnum, globalRef) ); 
SetStdProcs(myProcs); {use SetStdCProcs for a CGrafPort} 


myWindow*.grafProcs := @myProcs; 
myProcs.putPicProc := @putPICTdata; 
Zero := 0; 

LongCount := 2; 

PICTCount := SizeOf(Picture) ; 


{now write out the 512 byte header and zero (initially) the} 
{ Picture structure} 
FOR i := 1 TO (512 + SizeOf(Picture)) DIV LongCount DO 
Signal(FSWrite(globalRef, lLongCount, @Zero)); 
{open a new picture and draw the old one to it; this will convert} 
{ the old picture to fit the type of GrafPort to which we are} 
{ currently set} 

pFrame := PICThand**.picFrame; 

newPICTHand := NIL; 

newPICTHand := OpenPicture(pFrame) ; 

DrawPicture(PICTHand, pFrame); {draw the picture so the 
bottleneck will be used. In real life you could be spooling while 
doing drawing commands (you might not use DrawPicture) } 

ClosePicture; 

Signal(SetFPos(globalRef, fsFromStart, 512)); 

{skip the MacDraw header} 

LongCount := SizeOf(Picture) ; 

{write out the correct (low word of the) size and the frame at} 
{ the beginning} 

Signal (FSWrite(globalRef, longCount, Ptr(newPICTHand%) ) ); 

Signal (FSClose(globalRef) ) ; 

myWindow*.grafProcs := NIL; 

KillPicture(newPICTHand) ; 

END 
ELSE 
Signal(err); 
END; {IF reply.good} 
END; {OutPICT} 


Drawing to an Offscreen Pixel Map 


With the advent of high resolution output devices such as laser printers, it has 
become necessary to support bitmap images at resolutions higher than those 
Supported by the screen. To speed up the interactive manipulation of high- 
resolution pixel map images, developers may want to first draw them into an off 
screen pixel map at screen resolution and retain this screen version as long as 
the document is open. 


Note: You can use the formula shown in the section "Sample PICT file" to 
calculate the resolution of the source data. How to draw into an 
offscreen pixmap is described in Macintosh Technical Note #120, 
"Drawing Into an Off-Screen Pixel Map"; the Graphics Devices chapter 
also contains a section describing how to draw to an offscreen device. 
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New GrafProcs Record 


The entire opcode space has been defined or reserved, as shown in the PICT 
Opcodes section in Table 3, and a new set of routines has been added to the 
grafProcs record. These changes provide support for anticipated future 
enhancements in a way that won't cause old applications to crash. It works like 
this: when Color QuickDraw encounters an unused opcode, it calls the new 
opcodeProc routine to parse the opcode data. By default, this routine simply 
ignores the data, since no new opcodes are defined (other than HeaderOp, which 
is also ignored). 


Color QuickDraw has replaced the QDProcs record with a CQDProcs record. Ina 
new grafPort, you should never use the SetStdProcs routine. If you do, it will 
return the old QDProcs record, which won't contain an entry for the 
stdOpcodeProc. If you don't use the new SetStdCProcs routine, the first color 
picture that you try to display may crash your system. 

The CQDProcs record structure is shown below. Only the last seven fields are 
new; the rest of the fields are the same as those in the QDProcs record. 


CQDProcsPtr = *CQDProcs 
CQDProcs = RECORD 
textProc: Ptr; 
LineProc: Ptr; 
rectProc: Ptr; 
rRectProc: Ptr; 
ovalProc: Ptr; 
arcProc: Ptr; 
polyProc: Ptr; 
rgnProc: Ptr; 
bitsProc: Ptr; 
commentProc: Ptr; 
txMeasProc: Ptr; 
getPicProc: Ptr; 
putPicProc: Ptr; 
opcodeProc: Ptr; {fields added to QDProcs} 
newProcl: Ptr; {reserved for future use} 
newProc2: Ptr; {reserved for future use} 
newProc3: Ptr; {reserved for future use} 
newProc4: Ptr; {reserved for future use} 
newProc5: Ptr; {reserved for future use} 
newProc6: Ptr; {reserved for future use} 
END; 


Picture Compatibility 


Many applications already support PICT resources larger than 32K. The 128K ROMs 
(and later) allow pictures as large as memory (or spooling) will accommodate. 
This was made possible by having QuickDraw ignore the size word and simply read 
the picture until the end-of-picture opcode is reached. 


Note: For maximum safety and convenience, let QuickDraw generate and 
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interpret your pictures. 


While the PICT data formats described in this section allow you to read or write 
picture data directly, it's best to let DrawPicture or OpenPicture and 
ClosePicture process the opcodes. 


One reason to read a picture directly by scanning the opcodes is to disassemble 
it; for example, extracting a Color QuickDraw pixel map to store in a private 
data structure. This shouldn't normally be necessary, unless your application is 
running on a CPU other than the Macintosh. You wouldn't need to do it, of 
course, if you were using Color QuickDraw. 


If your application does use the picture data, be sure it checks the version 
information. You may want to include an alert box in your application, 
indicating to users whether a picture was created using a later version of the 
picture format than is currently recognized by your application, and letting 
them know that some elements of the picture can't be displayed. If the version 
information indicates a QuickDraw picture version later than the one recognized 
by your application, your program should skip over the new opcodes and only 
attempt to parse the opcodes it knows. 


As with reading picture data directly, it's best to use QuickDraw to create data 
in the PICT format. If you need to create PICT format data directly, it's 
essential that you understand and follow the format presented in Table 3 and 
thoroughly test the data produced on both color and black and white Macintosh 
machines. 


Picture Format 


This section describes the internal structure of the QuickDraw picture, 
consisting of a fixed-length header (which is different for version 1 and 
version 2 pictures), followed by variable-sized picture data. Your picture 
structure must follow the order shown in the examples below. 


The two fixed-length fields, picSize and picFrame, are the same for version 1 
and version 2 pictures. 


picSize: INTEGER; {low-order 16 bits of picture size} 
picFrame: RECT; {picture frame, used as scaling reference} 


Following these fields is a variable amount of opcode-driven data. Opcodes 
represent drawing commands and parameters that affect those drawing commands in 
the picture. The first opcode in any picture must be the version opcode, 
followed by the version number of the picture. 


Picture Definition: Version 1 


In a version 1 picture, the version opcode is $11, which is followed by version 
number $01. When parsing a version 1 picture, Color QuickDraw (or a patched 
QuickDraw) assumes it's reading an old picture, fetching a byte at a time as 
opcodes. An end-of-picture byte ($FF) after the last opcode or data byte in the 
file signals the end of the data stream. 


Picture Header (fixed size of 2 bytes): 
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$11 BYTE {version opcode} 
$01 BYTE {version number of picture} 


Picture Definition Data (variable sized): 


opcode BYTE {one drawing command} 
data . 

opcode BYTE {one drawing command} 
data . 

$FF f{end-of-picture opcode} 


Picture Definition: Version 2 


In a version 2 picture, the first opcode is a two-byte version opcode ($0011). 
This is followed by a two-byte version number ($02FF). On machines without the 
4.1 System file, the first $00 byte is skipped, then the $11 is interpreted as a 
version opcode. On a Macintosh II (or a Macintosh with System file 4.1 or 
later), this field identifies the picture as a version 2 picture, and all 
subsequent opcodes are read as words (which are word-aligned within the 
picture). On a Macintosh without the 4.1 System patch, the $02 is read as the 
version number, then the $FF is read and interpreted as the end-of-picture 
opcode. For this reason, DrawPicture terminates without drawing anything. 


Picture Header (fixed size of 30 bytes): 


$0011 WORD {version opcode} 

$02FF WORD {version number of new picture} 
$0CO0 WORD {reserved header opcode} 

24 bytes of data {reserved for future Apple use} 


Picture Definition Data (variable sized): 


opcode WORD {one drawing command} 
data... 

opcode WORD {one drawing command} 
data . 

$00FF WORD f{end-of-picture opcode} 


For future expandibility, the second opcode in every version 2 picture must be a 
reserved header opcode, followed by 24 bytes of data that aren't used by your 
application. 


PicComments 


If your application requires capability beyond that provided by the picture 
opcodes, the picComment opcode allows data or commands to be passed directly to 
the output device. PicComments enable MacDraw, for example, to reconstruct 
graphics primitives not found in QuickDraw (such as rotated text) that are 
received either from the Clipboard or from another application. PicComments are 
also used as a means of communicating more effectively with the LaserWriter and 
with other applications via the scrap or the PICT data file. 
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Because some operations (like splines and rotated text) can be implemented more 
efficiently by the LaserWriter, some of the picture comments are designed to be 
issued along with QuickDraw commands that simulate the commented commands on the 
Macintosh screen. If the printer you are using has not implemented the comment 
commands, it ignores them and simulates the operations using the accompanying 
QuickDraw commands. Otherwise, it uses the comments to implement the desired 
effect and ignores the appropriate QuickDraw-simulated commands. 


If you are going to produce or modify your own picture, the structure and use of 
these comments must be precise. The comments and the embedded QuickDraw commands 
must come in the correct sequence in order to work properly. 


Note: Apple is currently investigating a method to register picComments. 
If you intend to use new picComments in your application, you must 
contact Apple's Developer Technical Support to avoid conflict with 
picComment numbers used by other developers. 


Sample PICT File 


An example of a version 2 picture data file that can display a single image is 
shown in Table 1. Applications that generate picture data should set the 
resolution of the image source data in the hRes and vRes fields of the PICT 
file. It's recommended, however, that you calculate the image resolution anyway, 
using the values for srcRect and dstRect according to the following formulas: 


horizontal resolution (hRes) = width of srcRect x 72 


width of dstRect 


vertical resolution (vRes) height of srcRect x 72 


height of dstRect 


Table 1-PICT file example 


Size Name Description 
(in bytes) 

2 picSize low word of picture size 

8 picFrame rectangular bounding box of picture, 
at 72 dpi 

Picture Definition Data: 

2 version op version opcode = $0011 

2 version version number = $02FF 

2 Header op header opcode = $0C00 

4 size total size of picture in bytes 
(-1 for version 2 pictures) 

16 fBBox fixed-point bounding box 
(-1 for version 2 pictures) 

4 reserved reserved for future Apple use 
(-1 for version 2 pictures) 

2 opbitsRect bitMap opcode = $0090 

2 rowBytes integer, must have high bit set to 
Signal pixMap 

8 bounds rectangle, bounding rectangle at 


source resolution 
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2 pmVersion integer, pixMap version number 

2 packType integer, defines packing format 

4 packSize LongInt, length of pixel data 

4 hRes fixed, horizontal resolution (dpi) of 
source data 

4 vRes fixed, vertical resolution (dpi) of 
source data 

2 pixelType integer, defines pixel type 

2 pixelSize integer, number of bits in pixel 

2 cmpCount integer, number of components in pixel 

2 cmpSize integer, number of bits per component 

4 planeBytes LongInt, offset to next plane 

pmTable color table = 0 
pmReserved reserved = 0 

4 ctSeed LongInt, color table seed 

2 ctFlags integer, flags for color table 

2 ctSize integer, number of entries in ctTable —1 

(ctSize+1l) * 8 ctTable color lookup table data 

8 srcRect rectangle, source rectangle at source 
resolution 

8 dstRect rectangle, destination rectangle at 72 dpi 
resolution 

2 mode integer, transfer mode 

see Table 5 pixData pixel data 
2 endPICT op end-of-picture opcode = $00FF 


Color Picture Routines 


FUNCTION OpenPicture (picFrame: Rect) PicHandle; 

The OpenPicture routine has been modified to take advantage of QuickDraw's new 
color capabilities. If the current port is a cGrafPort, then OpenPicture 
automatically opens a version 2 picture, as described in the previous section. 
As before, you close the picture using ClosePicture and draw the picture using 
DrawPicture. 
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PICT OPCODES 


The opcode information in Table 3 is provided for the purpose of debugging 
application-generated PICT files. Your application should generate and read PICT 
files only by using standard QuickDraw or Color QuickDraw routines 

(OpenPicture, ClosePicture). 


The data types listed in Table 2 are used in the Table 3 opcode definitions. 
Data formats are described in Volume I. 


Table 2—Data types 


Type Size 

vl opcode 1 byte 

v2 opcode 2 bytes 

integer 2 bytes 

long integer 4 bytes 

mode 2 bytes 

point 4 bytes 

0..255 1 byte 

—128..127 1 byte (signed) 

rect 8 bytes (top, left, bottom, right: integer) 
poly 10+ bytes 

region 10+ bytes 

fixed-point number 4 bytes 

pattern 8 bytes 

rowbytes 2 bytes (always an even quantity) 


Valid picture opcodes are listed in Table 3. New opcodes or those altered for 
version 2 picture files are indicated by a leading asterisk (*). The unused 
opcodes found throughout the table are reserved for Apple use. The length of the 
data that follows these opcodes is pre-defined, so if they are encountered in 
pictures, they can simply be skipped. By default, Color QuickDraw reads and then 
ignores these opcodes. 


Table 3—PICT opcodes 


Opcode Name Description Data Size 
(in bytes) 

$0000 NOP nop 0 

$0001 Clip clip region size 

$0002 BkPat background pattern 8 

$0003 TxFont text font (word) 2 

$0004 TxFace text face (byte) 1 

$0005 TxMode text mode (word) 2 

$0006 SpExtra space extra (fixed point) 4 

$0007 PnSize pen size (point) 4 

$0008 PnMode pen mode (word) 2 

$0009 PnPat pen pattern 8 

$000A FillPat fill pattern 8 
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$000B 
$000C 
$000D 
$000E 
$000F 
$0010 
$0011 
$0012 
$0013 
$0014 
$0015 
$0016 
$0017 
$0018 
$0019 
$001A 
$001B 


$001C 
$001D 


$001E 
$001F 


$0020 
$0021 
$0022 


$0023 
$0024 


$0025 
$0026 
$0027 
$0028 
$0029 
$002A 
$002B 
$002C 
$002D 
$002E 
$002F 


OvSize 

Origin 

TxSize 

FgColor 

BkColor 

TxRatio 

Version 

*BkPixPat 

*PnPixPat 

*FilLPixPat 

*PnLocHFrac 

*ChExtra 

*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
*RGBFgCol 

*RGBBkCol 


*HiliteMode 
*HiliteColor 


*DefHilite 
*OpColor 


Line 
LineFrom 
ShortLine 


ShortLineFrom 
*reserved for Apple use 


*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 
LongText 

DHText 

DVText 

DHDVText 

*reserved for Apple use 
*reserved for Apple use 
*reserved for Apple use 


*reserved for Apple use 
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oval size (point) 

dh, dv (word) 

text size (word) 
foreground color (long) 
background color (long) 


numer (point), denom (point) 


version (byte) 
color background pattern 


color pen pattern 
color fill pattern 


fractional pen position 
extra for each character 
opcode 

opcode 

opcode 

RGB foreColor 


RGB backColor 


hilite mode flag 
RGB hilite color 


Use default hilite color 
RGB OpColor for 
arithmetic modes 


pnLoc (point), newPt (point) 


newPt (point) 

pnLoc (point, dh, dv 
(-128..127) 

dh, dv (-128..127) 


opcode + 2 bytes data 
length + data 
opcode + 2 bytes data 
length + data 
opcode + 2 bytes data 
length + data 
opcode + 2 bytes data 


length + data 

txLoc (point), count 
(0..255), text 

dh (0..255), count 
(0..255), text 

dv (@..255), count 
(0..255), text 

dh, dv (0..255), count 
(0..255), text 

opcode + 2 bytes data 


length + data 
opcode + 2 bytes data 
length + data 
opcode + 2 bytes data 
length + data 
opcode + 2 bytes data 


4 
4 
2 
4 
4 
8 
1 


variable: 
see Table 
variable: 
see Table 
variable: 
see Table 
2 
2 
0 
0 
0 
variable: 
see Table 
variable: 
see Table 
0 
variable: 
see Table 
0 
variable: 
see Table 
8 
4 
6 


2 

2+ data 
length 
2+ data 
length 
2+ data 
length 
2+ data 
length 

5 + text 


2 + text 
2 + text 
3 + text 


2+ data 
length 
2+ data 
length 
2+ data 
length 
2+ data 


length + data length 


$0030 frameRect rect 
$0031 paintRect rect 
$0032 eraseRect rect 
$0033 invertRect rect 
$0034 fillRect rect 


$0035 *reserved for Apple use opcode + 8 bytes data 
$0036 *reserved for Apple use opcode + 8 bytes data 
$0037 *reserved for Apple use opcode + 8 bytes data 


$0038 frameSameRect rect 

$0039 paintSameRect rect 

$003A eraseSameRect rect 

$003B invertSameRect rect 

$003C fillSameRect rectangle 

$003D *reserved for Apple use opcode 

$003E *reserved for Apple use opcode 

$003F *reserved for Apple use opcode 

$0040 frameRRect rect (see Note #5 ) 
$0041 paintRRect rect (see Note #5 ) 
$0042 eraseRRect rect (see Note #5 ) 
$0043 invertRRect rect (see Note #5 ) 
$0044 fillRRect rect (see Note #5 ) 


$0045 *reserved for Apple use opcode + 8 bytes data 
$0046 *reserved for Apple use opcode + 8 bytes data 
$0047 *reserved for Apple use opcode + 8 bytes data 


$0048 f rameSameRRect rect 
$0049 paintSameRRect rect 
$004A eraseSameRRect rect 
$004B invertSameRRect rect 
$004C fillSameRRect rect 


$004D *reserved for Apple use opcode 
$004E *reserved for Apple use opcode 
$004F *reserved for Apple use opcode 


DODDDDADADAAADAAAADADADDADDADDADAAADADAADAADAWDDDDDUDVGUONOMWO WO WO OM OO CO 


$0050 frameOval rect 

$0051 paintOval rect 

$0052 eraseOval rect 

$0053 invertOval rect 

$0054 Filloval rect 

$0055 *reserved for Apple use opcode + 8 bytes data 

$0056 *reserved for Apple use opcode + 8 bytes data 

$0057 *reserved for Apple use opcode + 8 bytes data 

$0058 frameSameOval rect 

$0059 paintSameOval rect 

$005A eraseSameOval rect 

$005B invertSameOval rect 

$005C fillSameOval rect 

$005D *reserved for Apple use opcode 

$005E *reserved for Apple use opcode 

$005F *reserved for Apple use opcode 

$0060 frameArc rect, startAngle, arcAngle 12 
$0061 paintArc rect, startAngle, arcAngle 12 
$0062 eraseArc rect, startAngle, arcAngle 12 
$0063 invertArc rect, startAngle, arcAngle 12 
$0064 fillArc rect, startAngle, arcAngle 12 
$0065 *reserved for Apple use opcode + 12 bytes 12 
$0066 *reserved for Apple use opcode + 12 bytes 12 
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$0067 *reserved for Apple use opcode + 12 bytes 12 

$0068 frameSameArc rect 4 

$0069 paintSameArc rect 4 

$006A eraseSameArc rect 4 

$006B invertSameArc rect 4 

$006C fillSameArc rect 4 

$006D *reserved for Apple use opcode + 4 bytes 4 

$006E *reserved for Apple use opcode + 4 bytes 4 

$006F *reserved for Apple use opcode + 4 bytes 4 
size 

$0070 framePoly poly polygon 
size 

$0071 paintPoly poly polygon 
size 

$0072 erasePoly poly polygon 
size 

$0073 invertPoly poly polygon 
size 

$0074 fillPoly poly polygon 
size 

$0075 *reserved for Apple use opcode + poly 

$0076 *reserved for Apple use opcode + poly 

$0077 *reserved for Apple use opcode word + poly 

$0078 frameSamePoly (not yet implemented: 0 

same as 70, etc) 

$0079 paintSamePoly (not yet implemented) 0 

$007A eraseSamePoly (not yet implemented) 0 

$007B invertSamePoly (not yet implemented) 0 

$007C fillSamePoly (not yet implemented) 0 

$007D *reserved for Apple use opcode 0 

$007E *reserved for Apple use opcode 0 

$007F *reserved for Apple use opcode 0 

$0080 frameRgn rgn region size 

$0081 paintRgn rgn region size 

$0082 eraseRgn rgn region size 

$0083 invertRgn rgn region size 

$0084 fillRgn rgn region size 

$0085 *reserved for Apple use opcode + rgn region size 

$0086 *reserved for Apple use opcode + rgn region size 

$0087 *reserved for Apple use opcode + rgn region size 

$0088 f rameSameRgn (not yet implemented: 0 

same as 80, etc.) 

$0089 paintSameRgn (not yet implemented) 0 

$008A eraseSameRgn (not yet implemented) 0 

$008B invertSameRgn (not yet implemented) 0 

$008C fillSameRgn (not yet implemented) 0 

$008D *reserved for Apple use opcode 0 

$008E *reserved for Apple use opcode 0 

$008F *reserved for Apple use opcode 0 

$0090 *BitsRect copybits, rect clipped variable: 
see Table 4 

$0091 *BitsRgn copybits, rgn clipped variable: 
see Table 4 

$0092 *reserved for Apple use opcode + 2 bytes data 2+ data 

length + data length 
$0093 *reserved for Apple use opcode + 2 bytes data 2+ data 
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length + data length 
$0094 *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$0095 *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$0096 *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$0097 *reserved for Apple use opcode word + 2 bytes 2+ data 
data length + data length 
$0098 *PackBitsRect packed copybits, rect variable: 
clipped see Table 4 
$0099 *PackBitsRgn packed copybits, rgn variable: 
clipped see Table 4 
$009A *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$009B *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$009C *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$009D *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$009E *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$009F *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$00A0 ShortComment kind (word) 2 
$00A1 LongComment kind (word), size 4+data 
(word), data 
$00A2 *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$00AF *reserved for Apple use opcode + 2 bytes data 2+ data 
length + data length 
$00BO0 *reserved for Apple use opcode 0 
$00CF *reserved for Apple use opcode 0 
$00D0 *reserved for Apple use opcode + 4 bytes data 4+ data 
length + data length 
$00FE *reserved for Apple use opcode + 4 bytes data 4+ data 
length + data length 
$00FF opEndPic end of picture 2 
$0100 *reserved for Apple use opcode + 2 bytes data 2 
$01FF *reserved for Apple use opcode + 2 bytes data 2 
$0200 *reserved for Apple use opcode + 4 bytes data 4 
$OBFF *reserved for Apple use opcode + 4 bytes data 22 
$0C00 HeaderOp opcode 24 
$0CO1 *reserved for Apple use opcode + 4 bytes data 24 
$7F00 *reserved for Apple use opcode + 254 bytes data 254 
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$7FFF 
$8000 


$80FF 
$8100 


$FFFF 


*reserved for Apple use 
*reserved for Apple use 


*reserved for Apple use 
*reserved for Apple use 


*reserved for Apple use 


opcode + 254 bytes data 254 


opcode 0 
opcode 0 
opcode + 4 bytes data 4+ data 
length + data length 
opcode + 4 bytes data 4+ data 
length + data length 


Notes to Table 3 


1. The opcode value has been extended to a word for version 2 pictures. 


Remember, opcode size 


= 1 byte for version 1. 


2. Because opcodes must be word aligned in version 2 pictures, a byte 
of 0 (zero) data is added after odd-size data. 
3. The size of reserved opcodes has been defined. They can occur only 
in version 2 pictures. 
4. All unused opcodes are reserved for future Apple use and should 
not be used. 


5. For opcodes $0040-$0044: 


of the ovSize point (refer to opcode $000B) 
6. For opcodes $0090 and $0091: data is unpacked. These opcodes can 
only be used for rowbytes less than 8. 
7. For opcodes $0100-$7FFF: the amount of data for opcode 


$nnXX = 2 * nn bytes. 


rounded-corner rectangles use the setting 


The New Opcodes: Expanded Format 


The expanded format of the version 2 PICT opcodes is shown in Table 4 below. 


Table 4—Data Format of Version 2 PICT Opcodes 


Opcode 
$0012 
$0013 


$0014 
$0015 


$0016 


$001A 
$001B 


$001D 
$001F 


Name 
BkPixPat 
PnPixPat 


FillPixPat 
PnLocHFrac 


ChExtra 


RGBFgCol 
RGBBkCol 


HiliteColor 
OpColor 


Description 


color background pattern 
color pen pattern 

color fill pattern 
fractional pen 

position (word) 


extra for each 
character (word) 

RGB foreColor (RBGColor) 

RGB backColor (RGBColor) 


RGB hilite color 
RGB OpColor for 


Reference to Notes 


See Note 1 

See Note 1 

See Note 1 

If pnLocHFrac <> 1/2, it 
is always put to the 
picture before each 
text drawing operation. 

After chExtra changes, 
it is put to picture 
before next text 
drawing operation. 

desired RGB for 
foreground 

desired RGB for 
background 
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arithmetic modes 
$001C HiliteMode hilite mode flag No data; this opcode is 
sent before a drawing 
operation that uses the 
hilite mode. 


$O001E DefHilite Use default hilite No data; set hilite 

color to default (from low 
memory) . 

$0090 BitsRect copybits, rect See Note 2,4,5 
clipped 

$0091 BitsRgn copybits, rgn See Note 3,4,5 
clipped 

$0098 PackBitsRect packed copybits, See Note 2,4 
rect clipped 

$0099 PackBitsRgn packed copybits, See Note 3,4 


rgn clipped 


Notes to Table 4 


1. if patType = ditherPat 


then 
PatType: word; {pattern type = 2} 
PatiData: Pattern; {old pattern data} 
RGB: RGBColor; {desired RGB for pattern} 
else 
PatType: word; {pattern type = 1} 
PatiData: Pattern; fold pattern data} 
pixMap: {described in Table 5} 
colorTable: {described in Table 5} 
pixData: {described in Table 5} 
end; 

2.  pixMap: {described in Table 5} 
colorTable: {described in Table 5} 
srcRect: Rect; {source rectangle} 
dstRect: Rect; {destination rectangle} 
mode: Word; {transfer mode (may include new transfer } 

{ modes) } 
PixData: {described in Table 5} 

3. pixMap: {described in Table 5 } 
colorTable: {described in Table 5 } 
srcRect: Rect; {source rectangle} 
dstRect: Rect; {destination rectangle} 
mode: Word; {transfer mode (may include new transfer } 

{ modes) } 
maskRgn: Rgn; {region for masking} 
PixData: {described in Table 5} 


4. These four opcodes ($0090, $0091, $0098, $0099) are modifications of 
existing (version 1) opcodes. The first word following the opcode is 
the rowBytes. If the high bit of the rowBytes is set, then it is a 
pixMap containing multiple bits per pixel; if it is not set, it is a 
bitMap containing one bit per pixel. In general, the difference between 
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version 1 and version 2 formats is that the pixMap replaces the bitMap, 
a color table has been added, and pixData replaces the bitData. 


5. Opcodes $0090 and $0091 are used only for rowbytes less than 8. 


Table 5—Data Types Found Within New PICT Opcodes Listed in Table 4 


Data Type Field Definitions Comments 
pixMap = baseAddr: long; {unused = 0} 
rowBytes: word; {rowBytes w/high byte set} 
Bounds: rect; {bounding rectangle} 
version: word; {version number = 0} 
packType: word; {packing format = 0} 
packSize: long; {packed size = 0} 
hRes: fixed; {horizontal resolution (default = } 
{ $0048 .0000) } 
vRes: fixed; {vertical resolution (default= } 
{ $0048 .0000) } 
pixelType: word; {chunky format = 0} 
pixelSize: word; {# bits per pixel (1,2,4,8)} 
cmpCount: word; {# components in pixel = 1} 
cmpSize: word; {size of each component = pixelSize } 
{ for chunky} 
planeBytes: long; {offset to next plane = 0} 
pmTable: long; {color table = 0} 
pmReserved: long; {reserved = 0} 
end; 
colorTable = ctSeed: long; {id number for color table = 0} 
ctFlags: word; {flags word = 0} 
ctSize: word; {number of ctTable entries-1 } 


{ ctSize + 1 color table entries } 
{ each entry = pixel value, red, } 
{ green, blue: word} 

end; 


pixData: {the following pseudocode describes the pixData data type} 

If rowBytes < 8 then data is unpacked 
data size = rowBytes*(bounds.bottom-bounds.top) ; 

If rowBytes >= 8 then data is packed. 
Image contains (bounds.bottom-bounds.top) packed scanlines. 
Packed scanlines are produced by the PackBits routine. 
Each scanline consists of [byteCount] [data]. 
If rowBytes > 250 then byteCount is a word, 

else it is a byte. 

end; 
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SUMMARY OF COLOR QUICKDRAW 


Constants 

CONST 
{ Old-style grafPort colors } 
blackColor = 33; 
whiteColor = 30; 
redColor = 209; 
greenColor = 329; 
blueColor = 389; 
cyanColor = 269; 
magentaColor = 149; 
yellowColor = 89; 


{ Arithmetic transfer modes } 


blend = 32: 
addPin = 33; 
addOver = 34; 
subPin = 35; 
adMax = 37; 
subOver = 38; 
adMin = 39; 


{ Transparent mode constant } 
transparent = 36; 

{ Text mask constant } 

mask = 64; 

{ Highlight constants } 


hilite 
pHiliteBit 


50; 

0; {this is the correct value for use when } 
{ calling the BitClear trap. BClr must use } 
{ the assembly language equate hiliteBit} 


{ Constant for resource IDs } 


defQDColors = 127; 


Data Types 


TYPE 
RGBColor = RECORD 
red: INTEGER; {red component} 
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green: INTEGER; {green component} 
blue: INTEGER {blue component} 
END; 
ColorSpec = RECORD 
value: INTEGER; {index or other value} 
rgb: RGBColor {true color} 
END; 
cSpecArray : ARRAY [0..0] of ColorSpec; 
CTabHandle = *“CTabPtr; 
CTabPtr = “ColorTable; 
ColorTable = RECORD 
ctSeed: LONGINT; {unique identifier from table} 
ctFlags: INTEGER; {high bit is 1 for device, 0 } 
{ for pixMap} 
ctSize: INTEGER; {number of entries -1 in } 
{ ctTable} 
ctTable: cSpecArray 
END; 
CGrafPtr = *CGrafPort; 
CGrafPort = RECORD 
device: INTEGER; {device ID for font selection} 
portPixMap: PixMapHandle; {port's pixel map} 
portVersion: INTEGER; {highest 2 bits always set} 
grafVars: Handle; {handle to more fields} 
chExtra: INTEGER; {extra characters placed} 
{ on the end of a string} 
pnLocHFrac: INTEGER; {pen fraction} 
portRect: Rect; {port rectangle} 
visRgn: RgnHandle; {visible region} 
clipRgn: RgnHandle; {clipping region} 
bkPixPat: PixPatHandle; {background pattern} 
rgbFgColor: RGBColor; {requested foreground color} 
rgbBkColor: RGBColor; {requested background color} 
pnLoc: Point; {pen location} 
pnSize: Point; {pen size} 
pnMode: INTEGER; {pen transfer mode} 
pnPixPat: PixPatHandle; {pen pattern} 
fillPixPat: PixPatHandle; {fill pattern} 
pnVis: INTEGER; {pen visibility} 
txFont: INTEGER; {font number for text} 
txFace: Style; {text's character style} 
txMode: INTEGER; {text's transfer mode} 
txSize: INTEGER; {font size for text} 
spExtra: Fixed; {extra space} 
fgColor: LONGINT; factual foreground color} 
bkColor: LONGINT; factual background color} 
colrBit: INTEGER; {plane being drawn} 
patStretch: INTEGER; {used internally} 
picSave: Handle; {picture being saved} 
rgnSave: Handle; {region being saved} 
polySave: Handle; {polygon being saved} 
grafProcs: CQDProcsPtr {low-level drawing routines} 
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END; 


GrafVars = RECORD 
rgbOpColor: RGBColor; 
rgbHiliteColor: RGBColor; 
pmFgColor: Handle; 
pmFgIndex: INTEGER; 
pmBkColor: Handle; 
pmBkIndex: INTEGER; 
pmF lags: INTEGER; 
END; 
PixMapHandle = “PixMapPtr; 
PixMapPtr = “PixMap; 
PixMap = RECORD 
baseAddr: Ptr; 
rowBytes: INTEGER; 
bounds: Rect; 
pmVersion: INTEGER; 
packType: INTEGER; 
packSize: LONGINT; 
hRes: Fixed; 
vRes: Fixed; 
pixelType: INTEGER; 
pixelSize: INTEGER; 
cmpCount: INTEGER; 
cmpSize: INTEGER; 
planeBytes: LONGINT; 
pmTable: CTabHandle; 
pmReserved: LONGINT 
END; 
PixPatHandle = *PixPatPtr; 
PixPatPtr = “PixPat; 
PixPat = RECORD 
patType: INTEGER; 
patMap: PixMapHandle; 
patData: Handle; 
patXData: Handle; 
patXValid: INTEGER; 
patXMap: Handle; 
patlData: Pattern; 
END; 
CCrsrHandle = *CCrsrPtr; 
CCrsrPtr = “CCrsr; 
CCrsr = RECORD 
crsrType: INTEGER; 
crsrMap: PixMapHandle; 
crsrData: Handle; 
crsrxData: Handle; 
crsrxValid: INTEGER; 
crsrXHandle: Handle; 
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{color for addPin, } 

{ subPin, and blend} 

{color for hiliting} 
{palette handle for } 

{ foreground color} 

{index value for foreground} 
{palette handle for } 

{ background color} 

{index value for background} 
{flags for Palette Manager} 


{pointer to pixMap data} 

{offset to next row} 

{boundary rectangle} 

{color QuickDraw version number} 
{packing format} 

{size of data in packed state} 
{horizontal resolution} 
{vertical resolution} 

{format of pixel image} 
{physical bits per pixel} 
{logical components per pixel} 
{logical bits per component} 
{offset to next plane} 

{absolute colors for this image} 
{reserved for future expansion} 


{pattern type} 

{pattern characteristics} 

{pixel image defining pattern} 
{expanded pixel image} 

{flags for expanded pattern data} 
{handle to expanded pattern data} 
{old-style pattern/RGB color} 


{type of cursor} 

{the cursor's pixMap} 
{cursor's data} 

{expanded cursor data} 
{depth of expanded data} 
{reserved for future use} 
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crsrlData: Bits16; {one-bit cursor} 


crsrMask: Bits16; {cursor's mask} 
crsrHotSpot: Point; {cursor's hotspot} 
crsrXTable: LONGINT; {private} 
crsrID: LONGINT; {ctSeed for expanded cursor} 
END; 

CIconHandle = “CIconPtr; 

CIconPtr = “CIcon; 

CIcon = RECORD 
iconPMap: PixMap; {the icon's pixMap} 
iconMask: BitMap; {the icon's mask bitMap} 
iconBMap: BitMap; {the icon's bitMap} 
iconData: Handle; {the icon's data} 


iconMaskData: ARRAY[@..0] OF INTEGER; {icon's } 
{ mask and bitMap data} 


END; 
MatchRec = RECORD 
red: INTEGER; {red component} 
green: INTEGER; {green component} 
blue: INTEGER; {blue component} 
matchData: LONGINT; 
END; 
CQDProcsPtr = *CQDProcs 
CQDProcs = RECORD 
textProc: Ptr; 
lineProc: Ptr; 
rectProc: Ptr; 
rRectProc: Ptr; 
ovalProc: Ptr; 
arcProc: Ptr; 
polyProc: Ptr; 
rgnProc: Ptr; 
bitsProc: Ptr; 
commentProc: Ptr; 
txMeasProc: Ptr; 
getPicProc: Ptr; 
putPicProc: Ptr; 
opcodeProc: Ptr; {fields added to QDProcs} 
newProcl: Ptr; {reserved for future use} 
newProc2: Ptr; {reserved for future use} 
newProc3: Ptr; {reserved for future use} 
newProc4: Ptr; {reserved for future use} 
newProc5: Ptr; {reserved for future use} 
newProc6: Ptr; {reserved for future use} 
END; 
Routines 


Operations on cGrafPorts 


PROCEDURE OpenCPort (port: CGrafPtr); 
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PROCEDURE InitCPort (port: CGrafPtr); 
PROCEDURE CloseCPort (port: CGrafPtr) ; 


Setting the Foreground and Background Colors 


PROCEDURE RGBForeColor (color : RGBColor); 
PROCEDURE RGBBackColor (color : RGBColor); 
PROCEDURE GetForeColor (VAR color : RGBColor); 
PROCEDURE GetBackColor (VAR color : RGBColor); 
Creating Pixel Maps 

FUNCTION NewPixMap : PixMapHandle; 


PROCEDURE DisposPixMap (pm: PixMapHandlLe) ; 
PROCEDURE CopyPixMap (srcPM,dstPM: PixMapHandle) ; 
Operations on Pixel Maps 

PROCEDURE CopyBits (srcBits, dstBits: BitMap; srcRect, dstRect: Rect; 

mode: INTEGER; maskRgn: RgnHandle) ; 

(srcBits,maskBits,dstBits: BitMap; 

srcRect, maskRect, dstRect: Rect); 

PROCEDURE SeedCFill (srcBits, dstBits: BitMap; srcRect, dstRect: Rect; 
seedH, seedV: INTEGER; matchProc: ProcPtr; 
matchData: LONGINT) ; 

PROCEDURE CalcCMask (srcBits, dstBits: BitMap; srcRect, dstRect: Rect; 
seedRGB: RGBColor; matchProc: ProcPtr; matchData: 


PROCEDURE CopyMask 


LONGINT) ; 
Operations on Pixel Patterns 


FUNCTION NewPixPat PixPatHandle; 

PROCEDURE DisposPixPat (ppat: PixPatHandle) ; 

FUNCTION GetPixPat (patID: INTEGER): PixPatHandle; 
PROCEDURE CopyPixPat (srcPP,dstPP: PixPatHandle) ; 

PROCEDURE MakeRGBPat (ppat: PixPatHandle; myColor: RGBColor); 
PROCEDURE PenPixPat (ppat: PixPatHandle) ; 

PROCEDURE BackPixPat (ppat: PixPatHandle) ; 


Color Drawing Operations 


PROCEDURE FillCRect (r: Rect; ppat: PixPatHandle) ; 
PROCEDURE FillCOval (r: Rect; ppat: PixPatHandle) ; 
PROCEDURE FillCRoundRect (r: Rect; ovWd,ovHt: INTEGER; ppat: PixPatHandle) ; 
PROCEDURE FillCArc (r: Rect; startAngle,arcAngle: INTEGER; 
ppat: PixPatHandle) ; 
PROCEDURE FillCRgn (rgn: RgnHandle; ppat: PixPatHandle) ; 
PROCEDURE FillCPoly (poly: PolyHandle; ppat: PixPatHandle) ; 
PROCEDURE GetCPixel (h,v: INTEGER; VAR cPix: RGBColor); 
PROCEDURE SetCPixel (h,v: INTEGER; cPix: RGBColor); 


Operations on Color Cursors 


FUNCTION GetCCursor (crsrID: INTEGER): CCrsrHandle; 
PROCEDURE SetCCursor (cCrsr: CCrsrHandle) ; 

PROCEDURE DisposCCursor (cCrsr: CCrsrHandle) ; 

PROCEDURE AllocCursor; 
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Operations on Icons 

FUNCTION GetCIcon (id: INTEGER): CIconHandle; 
PROCEDURE DisposCIcon (theIcon: CIconHandle) ; 
PROCEDURE PlotCIcon (theRect: Rect; theIcon: CIconHandle) ; 
Operations on cGrafPort Fields 

PROCEDURE SetPortPix (pm: PixMapHandle) ; 
PROCEDURE OpColor (color: RGBColor) ; 
PROCEDURE HiliteColor (color:RGBColor) ; 
PROCEDURE CharExtra (extra: Fixed); 

PROCEDURE SetStdCProcs (VAR cProcs: CQDProcs); 
Operations on Color Tables 


FUNCTION GetCTable (ctID: INTEGER): CTabHandle; 
PROCEDURE DisposCTable (ctTab: CTabHandle) ; 


Color Picture Operations 


FUNCTION OpenPicture (picFrame: Rect) : PicHandle; 


Global Variables 


HiliteMode {if the hilite mode is set, highlighting is on} 
HiliteRGB {default highlight color for the system} 


Assembly-Language Interface 


HiLite Constant 


hiliteBit EQU 7 ;flag bit in HiliteMode 
; this is the correct value for use in assembler 
; programs 


Equates for Resource IDs 
defQDColors EQU 127 sresource ID of clut for default QDColors 


RGBColor structure 


red EQU $0 ; [word] red channel intensity 
green EQU $2 ; [word] green channel intensity 
blue EQU $4 ; [word] blue channel intensity 
rgbColor EQU $6 ;Size of record 


ColorSpec structure 


value EQU $0 ; [short] value field 
rgb EQU $2 ;[rgbColor] rgb values 
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colorSpecSize EQU $8 ;Size of record 


Additional Offsets in a cGrafPort 


portPixMap EQU portBits ;[long] pixelMap handle 
portVersion EQU portPixMap+4 ; [word] port version number 
grafVars EQU portVersion+2 ; [long] handle to new fields 
chExtra EQU grafVars+4 ; [word] extra characters placed at 

; the end of a string 
pnLocHFrac EQU chExtra+2 ; [word] pen fraction 
bkPixPat EQU bkPat ;[long] handle to bk pattern 
rgbFgColor EQU bkPixPat+4 ;[6 bytes] RGB components of fg color 
rgbBkColor EQU RGBFgColor+6 ;[6 bytes] RGB components of bk color 
pnPixPat EQU $3A ;[long] handle to pen's pattern 
fillPixPat EQU pnPixPat+4 ;[long] handle to fill pattern 


Offsets Within GrafVars 


rgbOpColor EQU 0 ;[6 bytes] color for addPin, 

; subPin, and blend 
rgbHiliteColor EQU rgbOpColor+6 ;[6 bytes] color for hiliting 
pmFgColor EQU rgbHiliteColor+6 ;[4 bytes] Palette handle for 

; foreground color 
pmFgIndex EQU pmFgColor+4 ;[2 bytes] index value for 

; foreground 
pmBkColor EQU pmFgIndex+2 ;[4 bytes] Palette handle for 

; background color 
pmBkIndex EQU pmBkColor+4 ;[2 bytes] index value for 

; background 
pmF lags EQU pmBkIndex+2 ;[2 bytes] Flags for Palette 

; Manager 
grafVarRec EQU pmFlLags+2 ;size of grafVar record 


PixMap field offsets 


pmBaseAddr EQU $0 ; [long] 

pmNewF Lag EQU $4 ;[1 bit] upper bit of rowbytes is flag 
pmRowBytes EQU $4 s [word] 

pmBounds EQU $6 ; [rect] 

pmVersion EQU $E ; [word] pixMap version number 
pmPackType EQU $10 ; [word] defines packing format 
pmPackSize EQU $12 ; [long] Size of pixel data 

pmHRes EQU $16 ; [fixed] h. resolution (ppi) 

pmVRes EQU $1A ; [fixed] v. resolution (ppi) 


pmPixelType EQU $1E ; [word] defines pixel type 
pmPixelSize EQU $20 s [word] # bits in pixel 


pmCmpCount EQU $22 s [word] # components in pixel 
pmCmpSize EQU $24 s [word] # bits per field 
pmPlLaneBytes EQU $26 ; [long] offset to next plane 
pmTable EQU $2A ; [long] color map 

pmReserved EQU $2E ; [long] must be 0 

pmRec EQU $32 ; size of pixMap record 


PixPat field offsets 
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patType EQU $0 ;[word] type of pattern 


patMap EQU $2 ; [long] handle to pixmap 

patData EQU $6 ;[long] handle to data 

patXData EQU $A ;[ long] handle to expanded pattern data 
patXValid EQU $E ; [word] flags whether expanded pattern valid 
patXMap EQU $10 ;[long] handle to expanded pattern data 
patiData EQU $14 ;[8 bytes] old-style pattern/RGB color 

ppRec EQU $1C ; size of pixPat record 


Pattern Types 


oldPat EQU 0 ;foreground/background pattern 
newPat EQU 1 ;self-contained color pattern 
ditherPat EQU 2 ;rgb value to be dithered 
oldCrsrPat EQU $8000 ;old-style cursor 

CCrsrPat EQU $8001 ;new-style cursor 


CCrsr (Color Cursor) field offsets 


crsrType EQU 0 ; [word] cursor type 
crsrMap EQU crsrlypet+2 ;[long] handle to cursor's pixmap 
crsrData EQU crsrMap+4 ;[ long] handle to cursor's color data 
crsrxXData EQU crsrDatat+4 ;[long] handle to expanded data 
crsrxXValid EQU crsrXData+4 ; [word] handle to expanded data (0 if none) 
crsrXHandle EQU crsrxXValid+2 ;[long] handle for future use 
crsrlData EQU crsrXHandle+4 ;[16 words] one-bit data 
crsrMask EQU crsrlData+32 ;[16 words] one-bit mask 
crsrHotSpot EQU crsrMask+32 ; [point] hot-spot for cursor 
crsrXTable EQU crsrHotSpot+4 ;[long] private 
crsrID EQU crsrXTable+4 ;[long] color table seed for 

; expanded cursor 
crsrRec EQU crsrID+4 ;Size of cursor Save area 


CIcon (Color Icon) field offsets 


iconPMap EQU 0 ;[pixmap] icon's pixMap 

iconMask EQU iconPMap+pmRec ; [bitmap] 1-bit version of icon 
; 1-bit mask 

iconBMap EQU iconMask+bitmapRec ;[bitmap] 1-bit version of icon 


iconData EQU iconBMap+bitmapRec ;[long] Handle to pixMap data 
; followed by bMap and mask data 
iconRec EQU iconData+4 ;size of icon header 


Extensions to the QDProcs record 


opcodeProc EQU $34 ; [pointer] 
newProcl EQU $38 ; [pointer] 
newProc2 EQU $3C ; [pointer] 
newProc3 EQU $40 ; [pointer] 
newProc4 EQU $44 ; [pointer] 
newProc5 EQU $48 ; [pointer] 
newProc6 EQU $4C ; [pointer] 
cqdProcsRec EQU $50 ; size of QDProcs record 


MatchRec structure 


@ SpInside Macintosh * Version 1.0 * November 1989 « Apple Computer 
COLOR QUICKDRAW ¢ 76 of 78 


red EQU $0 [word] defined in RGBColor 


green EQU $2 [word] defined in RGBColor 

blue EQU $4 ; [word] defined in RGBColor 

matchData EQU $6 ; [long] 

matchRecSize EQU $A ;Size of record 

Global Variables 

HiliteMode EQU $938 ;if the hilite bit is set, highlighting is on 
HiliteRGB EQU $DA0 ;default highlight color for the system 
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Further Reference: 


QuickDraw 


Graphics Devices 
Color Manager 

Color Picker Package 
Palette Manager 
Resource Manager 


Technical 
Technical 
Technical 
Technical 
Technical 
Technical 


Note #21, QuickDraw's Internal Picture Definition 
Note #27, MacDraw's PICT File Format 

Note #120, Drawing Into an Off-Screen Pixel Map 
Note #163, Adding Color With CopyBits 

Note #171, _PackBits Data Format 

Note #244, A Leading Cause of Color Cursor Cursing 


32-Bit QuickDraw Documentation 


END OF DOCUMENT 


@ SpInside Macintosh ¢ Version 1.0 * November 1989 * Apple Computer 
COLOR QUICKDRAW ¢ 78 of 78 


